pi-plugin-cc — drive the Pi coding agent from Claude Code and Codex 🥧

English · 中文

External references: Pi coding agent · Pi RPC mode · Pi providers

A Claude Code plugin that delegates reviews and coding tasks to the Pi coding agent. Adapted from codex-plugin-cc, runtime swapped from Codex to Pi. Also usable from OpenAI's Codex CLI — see Use from Codex.

The hard dependency is pi, not any particular LLM. Pi can be configured for DeepSeek, OpenAI, Anthropic, Google, Ollama, LM Studio, or any OpenAI-compatible endpoint via ~/.pi/agent/models.json. The plugin defers all model selection to pi unless you override per command.

• Code review against the working tree or a branch base, with structured findings
• Adversarial review that challenges the design — not just spell-checks the diff
• Task delegation for diagnoses, refactors, and longer rescues, foreground or background
• Parallel fan-out — /pi:parallel-rescue runs multiple independent tasks concurrently via pi-subagents
• Sharded parallel review — /pi:review --shards <N> splits a large diff's changed files across N review jobs that run in parallel, then merges the findings
• Background job control — status, result, cancel, and stop-time review gate
• No OAuth — pi authenticates by API key (provider-specific), no codex login required

Integrates with pi-subagents (pi install npm:pi-subagents): /pi:setup detects it and lists the agent profiles, /pi:rescue prompts advertise the subagent tool to Pi, and /pi:parallel-rescue fans multiple tasks out to parallel child agents (scout, researcher, planner, worker, reviewer, …).

🔄 How it works

Codex's broker layer is gone — Pi is one-conversation-per-process, so the plugin spawns a fresh pi --mode rpc for each task. Background jobs are tracked in workspace-scoped state files. Review prompts inline the JSON schema since Pi has no outputSchema knob.

Slash commands

Every command accepts --model <id> to pin a specific model just for that run. With no --model and no env override (see Pick your model), pi falls back to whatever it has configured by default.

Quick Start

# 1. Install pi (required)
npm install -g --ignore-scripts @earendil-works/pi-coding-agent

# 2. Configure a provider — pick one
export OPENAI_API_KEY=sk-...           # OpenAI
export ANTHROPIC_API_KEY=sk-ant-...    # Anthropic
export GOOGLE_API_KEY=...              # Google
export DEEPSEEK_API_KEY=sk-...         # DeepSeek
# or run a local model: see https://github.com/earendil-works/pi (Ollama / LM Studio)

# 3. Verify pi sees a model
pi --list-models | head

Install the plugin in Claude Code:

> /plugin marketplace add Agents365-ai/pi-plugin-cc
> /plugin install pi@agents365-pi
> /reload-plugins
> /pi:setup

/pi:setup returns a readiness report. If pi is missing and npm is on PATH, it offers to install it for you.

Usage

> /pi:review
> /pi:review --base main
> /pi:review --model claude-sonnet-4
> /pi:review --out-file review.md
> /pi:adversarial-review focus on the new auth middleware
> /pi:rescue investigate why the Windows CI build is failing
> /pi:rescue --background --model gpt-4o refactor src/payments/
> /pi:parallel-rescue "audit the auth module" "benchmark the db queries" "update the API docs"
> /pi:status
> /pi:status task-mpgyiwb9-e3k641 --wait
> /pi:result task-mpgyiwb9-e3k641
> /pi:cancel task-mpgyiwb9-e3k641

--effort <off|minimal|low|medium|high|xhigh|max> is passed through to Pi via set_thinking_level. Models that do not support thinking silently ignore it (the plugin logs a one-line note to stderr when this happens).

--out-file <path> (on /pi:review, /pi:adversarial-review, /pi:rescue, /pi:result) writes Pi's full output to a file and returns only a short summary — verdict, finding counts, one line per finding. The heavy reasoning already runs on the cheaper model; this also keeps the large result out of the calling agent's context, so a big review doesn't burn Claude Code tokens on the relay. Open the file for the full detail.

--incremental (on /pi:review, /pi:adversarial-review) reviews only the commits since the last review on the current branch, using a per-branch cache of the last-reviewed commit — saving Pi input tokens and time by skipping the code that was already reviewed. Falls back to a full review when there is no valid cache.

🧩 Use from Codex

The core of this plugin is a harness-agnostic CLI (pi-companion.mjs) — any coding agent that can run shell commands can drive it. For OpenAI's Codex CLI, install the bundled custom prompts:

# 1. Clone the repo (anywhere; ~/pi-plugin-cc is the default the prompts assume)
git clone https://github.com/Agents365-ai/pi-plugin-cc ~/pi-plugin-cc

# 2. Install the Codex custom prompts
mkdir -p ~/.codex/prompts
cp ~/pi-plugin-cc/codex-prompts/*.md ~/.codex/prompts/

# 3. If you cloned somewhere else, point the prompts at it
echo 'export PI_PLUGIN_ROOT="$HOME/path/to/pi-plugin-cc"' >> ~/.zshrc

Then inside Codex: /pi-review, /pi-adversarial-review, /pi-rescue, /pi-parallel-rescue, /pi-status, /pi-result, /pi-cancel, /pi-setup (note - instead of : — Codex prompt names cannot contain colons).

Not available under Codex: the stop-time review gate and session-resume prompts (both rely on Claude Code hooks / subagents). Everything else — including pi-subagents parallel fan-out — works the same.

🧑‍⚖️ Multi-model review panel

One reviewer has blind spots; a panel doesn't share them. Passing --models to either review command runs the same diff through several models in parallel and merges their findings — issues reported by 2+ models rank first with a found by: tag:

> /pi:review --models deepseek-v4-flash,claude-sonnet-4-6,gpt-5-mini
> /pi:adversarial-review --models deepseek-v4-pro,o1 focus on concurrency

• Consensus findings (2+ models) are listed first; single-model findings follow.
• Duplicate findings are matched per file with line-range slack; severity escalates to the highest reported and alternate titles are kept.
• A member that fails (provider error, invalid JSON) is reported inline and does not sink the panel — it succeeds as long as one model returns a valid review.
• Panel members do not use the PI_PLUGIN_FALLBACK_MODELS chain — the panel itself is the redundancy.
• This only exists because Pi is provider-agnostic: a single-vendor CLI cannot convene a cross-vendor panel.

🛟 Automatic model fallback

Set a fallback chain once, and any failed run — provider outage, auth error, exhausted retries — is automatically retried with the next model:

export PI_PLUGIN_FALLBACK_MODELS=deepseek-v4-flash,MiniMax-M3

Applies to reviews and rescue tasks alike. When a fallback produced the result, the output ends with a Model fallback: note (and the JSON payload carries modelAttempts). /pi:setup shows the configured chain.

🏁 Model racing

For hard problems, run the same rescue task with several models in parallel and pick the winner:

> /pi:rescue --race deepseek-v4-pro,claude-sonnet-4-6 fix the flaky retry logic in src/queue.mjs
> /pi:rescue --race deepseek-v4-flash,gemini-2.5-pro why does the Windows CI build fail?

• Write races (--write, the /pi:rescue default): each racer works in an isolated git worktree created from HEAD — racers can never touch your working tree or each other. Each racer's result is captured as a patch; review them and apply exactly one with git apply <patch>.
• Read-only races (investigations): racers analyze the same tree; the output presents each answer side by side — agreement across models is a strong signal.
• A racer that fails or produces no changes is reported as such; the race succeeds while at least one racer finishes.
• Not combinable with --model or --resume (each racer starts a fresh session). Racers start from HEAD, so commit or stash first if the task concerns uncommitted work.

Pick your model

The plugin keeps three layers of model resolution:

Layer 1 wins over layer 2 wins over layer 3. None of the layers are required — leave them all unset and pi picks for you.

Suggested settings by provider

These are opinions, not requirements. Pick what fits your latency / cost / quality budget.

To make these defaults sticky:

export PI_PLUGIN_REVIEW_MODEL=claude-haiku-4-5
export PI_PLUGIN_ADVERSARIAL_REVIEW_MODEL=claude-sonnet-4-6

Value tier — cheaper than Claude/GPT, still competitive

The whole point of driving Pi is that you are not locked to Claude or GPT. These models cost a fraction of the frontier Claude/GPT tiers and, while not quite as strong, are more than good enough for everyday review and rescue work. Configure them in ~/.pi/agent/models.json (most are OpenAI-compatible endpoints) and use the exact id your provider exposes — verify with pi --list-models.

…and any other OpenAI-compatible endpoint you configure. Availability and the exact id depend on your ~/.pi/agent/models.json.

Not every model emits clean JSON for the structured review commands. If /pi:review fails with a parse error on a given model, it is still fine for /pi:rescue (free-form) — or add it to a PI_PLUGIN_FALLBACK_MODELS chain so a flaky member is retried with the next one. (Observed: some MiniMax and local models echo the prompt back instead of returning JSON.)

Configure pi

The minimum is a single env var with your API key. For richer setups, write ~/.pi/agent/models.json:

{
  "providers": {
    "deepseek": { "apiKey": "sk-..." },
    "openai":   { "apiKey": "sk-..." },
    "anthropic":{ "apiKey": "sk-ant-..." },
    "google":   { "apiKey": "..." },
    "openrouter": {
      "api": "openai-completions",
      "apiKey": "sk-or-v1-...",
      "baseUrl": "https://openrouter.ai/api/v1",
      "models": [
        {
          "id": "deepseek/deepseek-chat",
          "name": "DeepSeek via OpenRouter",
          "contextWindow": 128000,
          "maxTokens": 8192,
          "input": ["text"]
        }
      ]
    }
  }
}

Built-in providers (anthropic, openai, google, deepseek, ollama, lmstudio) only need apiKey (and optional baseUrl); pi ships their model lists. For custom OpenAI-compatible endpoints, set api: "openai-completions" and declare the models you want exposed.

Full reference: pi providers docs.

Stop-time review gate

Opt in with /pi:setup --enable-review-gate. When a Claude session ends, the plugin runs a Pi adversarial review of the previous turn and can block the stop if it finds material issues. If pi is unavailable while the gate is enabled, the hook blocks (it does not silently let the session end). Disable with /pi:setup --disable-review-gate.

🔗 Related projects

❤️ Support

If this plugin helps you, consider supporting the author:

WeChat Pay

Alipay

Buy Me a Coffee

Give a Reward

👤 Author

Agents365-ai

• GitHub: https://github.com/Agents365-ai
• Bilibili: https://space.bilibili.com/441831884

📄 License

Apache License 2.0. Forked from codex-plugin-cc (Apache-2.0, OpenAI) — see NOTICE.