Pi-Shell ACP桥接

Backend prerequisites

Claude / Codex ACP server packages (@agentclientprotocol/claude-agent-acp, @zed-industries/codex-acp) ship as pinned dependencies of pi-shell-acp; backend authentication still belongs to the operator's local CLI / runtime. Once the bridge is installed, the resolver picks the ACP server in this order:

1. CLAUDE_AGENT_ACP_COMMAND / CODEX_ACP_COMMAND env override — explicit override for an alternative binary or a wrapper command.
2. require.resolve(...) against the bundled package dependency — @agentclientprotocol/claude-agent-acp for Claude, @zed-industries/codex-acp for Codex. This is the default path; no extra global install needed.
3. PATH:claude-agent-acp / PATH:codex-acp fallback — used when the package resolution fails (e.g. a hand-edited node_modules).

Codex smoke (no global install required — the codex-acp pinned in dependencies is resolved automatically):

./run.sh smoke-codex /path/to/your-project

To force a global codex-acp (PATH fallback or development override):

pnpm add -g @zed-industries/codex-acp@0.14.0

Gemini is different — the gemini CLI binary is itself the ACP server, not a separate *-acp server package. It must be installed and authenticated on the operator's machine. Curated model: pi-shell-acp/gemini-3.1-pro-preview.

pnpm add -g @google/gemini-cli
gemini   # one-time interactive login (oauth-personal) or set GEMINI_API_KEY
./run.sh smoke-gemini /path/to/your-project

Backend is inferred from the model — Anthropic → claude, OpenAI → codex, Gemini → gemini. Set backend only to pin.

Install

pi-shell-acp is a thin ACP bridge — it connects pi to a local Claude/Codex/Gemini backend the operator has already installed and authenticated. The bridge does not provide Claude credentials, tokens, or subscription access, and does not bypass any backend auth. Whatever the operator's local claude / codex / gemini already trusts is what pi-shell-acp uses.

pi accepts four install sources for the bridge — npm: or git:, each in global (default, writes to ~/.pi/agent/settings.json) or project (-l flag, writes to .pi/settings.json) scope. A fifth path is a local clone for hacking on the bridge.

After installing the package, run run.sh install . in your target project. The script writes the piShellAcpProvider block into .pi/settings.json with the correct absolute path for pi-tools-bridge/start.sh — no hand-editing required. The exact location of run.sh depends on which install path was used (each section below shows it). For manual configuration, pi/settings.reference.json is the reference shape — see Settings below.

Settings

Reference shape lives in pi/settings.reference.json. Minimum:

{
  "compaction": { "enabled": false },
  "piShellAcpProvider": {
    "appendSystemPrompt": false,
    "settingSources": [],
    "strictMcpConfig": true,
    "showToolNotifications": true,
    "tools": ["Read", "Bash", "Edit", "Write"],
    "skillPlugins": [],
    "permissionAllow": ["Read(*)", "Bash(*)", "Edit(*)", "Write(*)", "mcp__*"],
    "mcpServers": {
      "pi-tools-bridge": {
        "command": "/path/to/pi-shell-acp/mcp/pi-tools-bridge/start.sh",
        "args": []
      }
    }
  }
}

mcpServers is the only ACP MCP injection path. In practice this repo is about the bundled pi-tools-bridge, which carries pi capabilities into ACP-backed sessions — not about being a general MCP catalog. Invalid entries throw McpServerConfigError — broken tool state surfaces as broken tool state. ./run.sh install writes the bundled pi-tools-bridge entry and prunes the legacy bundled session-bridge entry from older installs.

appendSystemPrompt: false is intentional. Pi / AGENTS context rides the first-user augment; putting it into the Claude _meta.systemPrompt carrier can route OAuth sessions to metered "extra usage" billing.

References

• File map + code-level invariants: AGENTS.md
• Current priority + open decisions: NEXT.md
• Release record: CHANGELOG.md
• xenodium/agent-shell — Emacs ACP client, resume > load > new idea origin
• agentclientprotocol/claude-agent-acp — canonical ACP server for Claude Code
• agent-config — real consumer repo

From source via pi — global (alternative)

pi install git:github.com/junghan0611/pi-shell-acp
cd /path/to/your-project
~/.pi/agent/git/github.com/junghan0611/pi-shell-acp/run.sh install .
~/.pi/agent/git/github.com/junghan0611/pi-shell-acp/run.sh smoke-all .