pi-plugin-cc
CLAUDE.md0 starsChanged 10 days agoApache-2.0View on GitHub
Guidance for AI agents (Claude Code, Codex, Pi, or any other) working in this repository. AGENTS.md is a symlink to this file. pi-plugin-cc is a Claude Code plugin that lets users delegate code reviews and coding tasks to Pi from inside Claude Code. It is a port of openai/codex-plugin-cc (Copyright 2026 OpenAI, Apache-2.0): same plugin structure, same command surface, same UX — but the runtime underneath is Pi instead of Codex. The guiding principle: seamless UX parity with codex-plugin-cc. When…
In this repository2 other files it gives its agents.
- releaseSkill
- sync-upstreamSkill
The file
We split this CLAUDE.md into the rules it gives an agent
6 rules. About 0 are common, 2 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 60
No runtime dependencies: Only Node stdlib. Keep it that way.
- Distinctive: line 72
Always run the full suite before declaring work done:
- Very specific: line 88
Use the sync-upstream skill.
- Very specific: line 95
Use the release skill. Run it once per pull request, after the code and tests are done.
- Very specific: line 115
Read-only runs need --no-mcp next to --tools read,grep,find,ls: --tools alone leaves MCP tools callable.
- Very specific: line 128
No HTML in Markdown table cells.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md
Guidance for AI agents (Claude Code, Codex, Pi, or any other) working in this repository.
AGENTS.md is a symlink to this file.
What this repo is
pi-plugin-cc is a Claude Code plugin that lets users delegate code reviews and coding tasks to
Pi from inside Claude Code. It is a port of openai/codex-plugin-cc
(Copyright 2026 OpenAI, Apache-2.0): same plugin structure, same command surface, same UX — but
the runtime underneath is Pi instead of Codex.
The guiding principle: seamless UX parity with codex-plugin-cc. When upstream adds or changes a feature, this repo should follow with the Pi-equivalent implementation, unless Pi fundamentally cannot support it (document that in COMPARISON.md).
Repo layout
.claude-plugin/marketplace.json Marketplace manifest (name: 5kahoisaac-pi)
plugins/pi/
.claude-plugin/plugin.json Plugin manifest
assets/icon.png Plugin icon (`icon` in plugin.json; directory listing only)
agents/pi-rescue.md Thin forwarding subagent
skills/ pi-cli-runtime + pi-result-handling (rescue forwarding rules)
commands/*.md Slash command prompts (review, task, rescue, ...)
hooks/hooks.json SessionStart / SessionEnd / Stop hook wiring
prompts/*.md Review, adversarial-review, and stop-gate prompt templates
schemas/review-output.schema.json Structured review JSON schema
scripts/
pi-companion.mjs Main CLI dispatcher (all subcommands)
session-lifecycle-hook.mjs Env capture + session-scoped job cleanup
stop-review-gate-hook.mjs Optional Stop-gate review
lib/*.mjs args, fs, git, job-control, pi, process, prompts,
render, state, tracked-jobs, workspace,
claude-session-transfer
tests/*.test.mjs node --test suites (unit + command-level)
tests/fake-pi.cjs Fake `pi` binary emitting Pi's JSONL events per scenario
tests/fake-pi-fixture.mjs Installs the fake `pi` on PATH; reads its call log
scripts/dev.mjs Dev bind/unbind of the local plugin in Claude Code
scripts/bump-version.mjs Sets or checks the version in every manifest (upstream's)
.github/workflows/pull-request-ci.yml CI: claude plugin validate --strict, node --check, npm testArchitecture in one paragraph
codex-plugin-cc drives Codex through a long-lived app-server broker (JSON-RPC over a Unix
socket, ~5 lib modules). Pi has no shared server (its RPC mode is a child process that only its
parent can drive), and the plugin does not need one: it runs Pi headlessly per turn,
pi -p --mode json with --session-id <uuid> for tasks or --no-session for reviews, parsing
the JSONL event stream from stdout. Session persistence comes
from Pi's own session store (tasks resume via --session-id; users reopen them with
pi --session <id>), so there is no broker to manage, and no socket lifecycle. Job tracking, state
files, background workers (detached task-worker respawn), and the stop-gate hook all follow the
upstream design. See COMPARISON.md for the full mapping and rationale.
Working conventions
- Node 18.18+, ESM only (
"type": "module"). No TypeScript build step; plain.mjs. - No runtime dependencies. Only Node stdlib. Keep it that way.
- Prose in plugin files uses "Pi" (capitalized) as the agent name — never lowercase "pi" in
user-facing text (commands, agents, README). Lowercase only for literal commands, paths, and
flags (
pi -p,pi-companion.mjs,/pi:task). - Match upstream naming where possible:
pi-companion.mjs↔codex-companion.mjs,PI_COMPANION_SESSION_ID↔CODEX_COMPANION_SESSION_ID, state dirpi-companion↔codex-companion. This makes diffs against upstream easy to read. - Surgical changes. Touch only what the task requires. Don't refactor lib modules that aren't involved.
Testing
Always run the full suite before declaring work done:
npm test # node --test tests/*.test.mjs- Tests must pass with zero failures.
- New features synced from upstream require corresponding test changes — see the
sync-upstreamskill for the required workflow. - Command-level tests run against the fake
piintests/fake-pi.cjs. Add a scenario there rather than calling the realpior the network. - E2E sanity (optional, when Pi is configured):
node plugins/pi/scripts/pi-companion.mjs setupshould report ready.
Syncing from upstream
Use the sync-upstream skill. It defines the full procedure: clone upstream, diff against the
last synced release tag, check Pi's docs and behavior before porting each change, port it,
always update tests, record every Pi difference in COMPARISON.md, then run the release
skill.
Releasing a change
Use the release skill. Run it once per pull request, after the code and tests are done. It
compares the version with origin/main's and bumps it per Semantic Versioning when plugins/pi/
changed (users stay on their cached copy until the version changes). It sets every manifest with
npm run bump-version -- X.Y.Z, writes the CHANGELOG.md entry under that version (there is no
[Unreleased] section), updates only the other docs the change makes stale, and verifies the
result. It never commits, tags, or pushes. The PR template's checklist requires it.
Licensing guardrail
This repo contains software adapted from Apache-2.0-licensed codex-plugin-cc. Keep the Apache-2.0 LICENSE and the NOTICE files (root + plugins/pi) intact; the NOTICE must continue to carry the OpenAI attribution for adapted portions. Do not relicense to MIT.
Things that are easy to break
pi -pchild processes hang if their stdin is a pipe that never closes — always spawn withstdio: ["ignore", "pipe", "pipe"](seespawnPiProcessinlib/pi.mjs).pi auth checkrequires--modelor--provider; the plugin readsdefaultProvideranddefaultModelfrom$PI_CODING_AGENT_DIR/settings.jsonor~/.pi/agent/settings.json. Pi has noPI_MODELvariable.- Read-only runs need
--no-mcpnext to--tools read,grep,find,ls:--toolsalone leaves MCP tools callable. - Pi's
tool_execution_endcarries noargs; take them fromtool_execution_startbytoolCallId(seedescribeToolEndinlib/pi.mjs). - Split Pi's JSONL on LF only, after UTF-8 decoding; Node's
readlinealso splits on Unicode line separators that are valid inside JSON strings. - The stop-gate hook must never emit a decision on stdout except the single JSON line; stderr is for notes.
--cwdmust be invalueOptionsfor every companion subcommand that accepts it, or it gets parsed as a positional job id.- Cancel must send SIGTERM, never SIGKILL. Pi's bash tool runs each command in its own process group and kills those groups only from its SIGTERM handler; after a SIGKILL the command keeps running (COMPARISON.md §9).
- No HTML in Markdown table cells. Claude Code's terminal prints
<br>literally, and a table row cannot hold a line break; put lists below the table (COMPARISON.md §14). - Pi's flags and values decide what the plugin accepts, not upstream's. Check
pi --helpand Pi'sdocs/cli.mdbefore porting a flag or value: Pi has--thinkingand no effort setting (COMPARISON.md §6).
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

