pi-plugin-cc

Claude Code plugin that delegates work (review, rescue, transfer) to the Pi Coding Agent CLI (pi), with anti-destruction guardrails.

Faithful adaptation of openai/codex-plugin-cc for pi: same command surface, same review-gate and session mechanics, pi-native internal engine. Only intentional divergence: no broker/daemon JSON-RPC — specific to Codex's app-server, with no equivalent needed on the pi side since it is headless-native (background mode is handled by simple jobs, see below).

Installation

/plugin marketplace add IlhanTech/plugin-pi-cc
/plugin install pi@pi-agent

Prerequisites

• npm i -g @mariozechner/pi-coding-agent (Node >= 18). The pi binary must be on the PATH.
• Authentication: a provider key as an environment variable (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, ...) or pi login (interactive, Claude Pro/Max, ChatGPT, Copilot).
• Verify the installation with /pi:setup.

Commands

Command	Role	Write	Bash
/pi:setup	Checks node/pi/auth, enables or disables the review-gate	—	—
/pi:review	Read-only code review (working tree or branch)	no	no
/pi:adversarial-review	Adversarial review: challenges design decisions	no	no
/pi:rescue	Delegates a task to pi (pi-rescue agent)	opt-in (--write)	double opt-in (--allow-bash)
/pi:transfer	Transfers the current Claude Code session context into a pi session	no (read-only seed)	no
/pi:status	Lists or details running/finished jobs	—	—
/pi:result	Shows a job's final output	—	—
/pi:cancel	Cancels a running job	—	—

All commands go through the companion:

node "${CLAUDE_PLUGIN_ROOT}/scripts/pi-companion.mjs" <subcommand> "$ARGUMENTS"

Security model

pi has no native sandbox, no cwd confinement, no built-in allowlist — the only runtime control point available is its tool_call extension API. The plugin compensates with four independent layers:

Layer 1 — pi-guard.ts extension (the only real runtime rampart)

Loaded by pi itself (-e guard/pi-guard.ts) as soon as a run has access to write/edit/bash. Intercepts every tool_call:

• bash: blocks destructive or dangerous commands (rm -rf, dd, mkfs, shred, fork bombs, sudo, git push --force, git clean -fdx, curl|sh, access to ~/.ssh/~/.aws/.env, etc.) and any command referencing a path outside the workspace (PI_GUARD_WORKSPACE).
• write/edit: blocks any write outside the workspace or to sensitive files (.env, .git/, keys).
• Strict fail-safe: any internal analysis error blocks the action ({ block: true }). No UI in headless mode, so no ctx.ui.confirm — it blocks directly rather than waiting on a confirmation that would never come.
• If pi is invoked with write/bash but the guard cannot be loaded, the companion refuses to run rather than letting it through.

Layer 2 — read-only companion by default

pi-companion.mjs restricts pi's tools depending on the mode:

• By default (review, adversarial-review, task without flags): --tools read,grep,find — nothing to destroy, guard not needed.
• task --write: adds write,edit (never bash) + mandatorily loads the guard.
• task --write --allow-bash: adds bash on top — explicit double opt-in, guard mandatory, no execution without it.

Layer 3 — PreToolUse hook (protects the Claude Code session itself)

hooks/guard-hook.mjs inspects every Bash command issued by Claude Code (not by pi) with the same destructive patterns as layer 1, and refuses it via permissionDecision: "deny" before execution. A safety net independent of the pi guard — also protects against an rm -rf that Claude itself might attempt to run.

The review-gate (Stop hook, stop-review-gate-hook.mjs) is opt-in (/pi:setup --enable-review-gate, disabled by default as in codex): once enabled, it requires a fresh, read-only pi review before letting the session end.

Layer 4 — tests

tests/guard.test.mjs, tests/guard-hook.test.mjs, tests/guard-hardening.test.mjs, tests/companion.test.mjs prove that destructive patterns are blocked and legitimate operations pass, by driving pi through a fake binary (tests/fake-pi-fixture.mjs) that never executes anything real. No test launches the real pi or an actually destructive command; everything happens in temp folders.

---

Intentional divergence from codex-plugin-cc: no broker app-server/JSON-RPC daemon. That's a specificity of Codex's app-server integration; since pi is headless-native, the faithful equivalent is the companion's background job system (--background, tracked via /pi:status//pi:result//pi:cancel).