pi-extension-acp

A Pi extension that exposes ACP-driven coding agents as Pi tools.

Mirrors how OpenClaw uses acpx to delegate work to Claude Code / Codex / Cursor — but as a Pi extension rather than an OpenClaw plugin. The companion package pi-agent-acp goes the other direction (lets ACP clients call into Pi).

What it does

Registers one Pi tool per configured ACP agent. When Pi's LLM calls one of these tools, the extension:

1. Spawns the agent's ACP binary as a child process
2. Speaks ACP / JSON-RPC 2.0 on its stdio
3. Runs initialize → session/new → session/prompt
4. Streams the agent's text back via Pi's onUpdate
5. Returns the final assistant text as the tool result

Pi (LLM decides to call claude_code tool)
   │
   ▼  Pi tool execute() — this extension
spawn claude-agent-acp
   │  ACP / JSON-RPC 2.0 over stdio
   ▼
@agentclientprotocol/claude-agent-acp
   │
   ▼  internal SDK call
Anthropic Claude

Installation

# in the Pi user-config dir
mkdir -p ~/.pi/agent/extensions/acp
cd ~/.pi/agent/extensions/acp
git clone https://git.bun.cafe/roxy/pi-extension-acp.git .
npm install

Pi auto-discovers ~/.pi/agent/extensions/acp/index.ts on startup. Verify with /extensions or by asking Pi to call the claude_code tool.

For project-local install, put it at .pi/extensions/acp/ instead.

You'll also need the ACP wrapper packages for each agent you want to call:

# Subscription-based (Pro/Max plan, no API billing):
npm install -g @anthropic-ai/claude-code   # the actual Claude CLI
npm install -g claude-code-acp              # subprocess-spawning ACP wrapper

# Then one-time OAuth login (writes to ~/.claude/credentials.json):
claude auth login

# Optional, for Codex:
npm install -g @zed-industries/codex-acp

⚠️ Do NOT set ANTHROPIC_API_KEY in the environment that spawns claude-code-acp. If it's present, the Claude CLI bills as API usage instead of using your subscription. This extension automatically strips ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN from the child env for the claude_code tool — but if you change the default command, make sure to keep the stripEnv setting.

Built-in agents

Tool name	Spawned binary	Wrapper package	Billing
claude_code	claude-code-acp	claude-code-acp	Pro/Max subscription
codex	codex-acp	@zed-industries/codex-acp	OpenAI API

Config

All overrides are env vars (extensions don't get a config file slot in Pi):

Variable	Purpose
PI_ACP_CLAUDE_CMD	Override the claude_code tool's binary path
PI_ACP_CLAUDE_ARGS	JSON array of extra args, e.g. '["--model","sonnet"]'
PI_ACP_CODEX_CMD	Override the codex tool's binary path
PI_ACP_CODEX_ARGS	JSON array of extra args
PI_ACP_EXTRA_AGENTS	JSON object of additional agents to register

PI_ACP_EXTRA_AGENTS example:

{
  "opencode": {
    "command": "opencode-acp",
    "label": "OpenCode",
    "description": "Delegate to OpenCode."
  }
}

Status

Experimental — known gaps:

• requestPermission from child agents auto-allows. To wire up real user approval, the extension needs access to Pi's ctx.ui — easy follow-up, just plumb it through.
• File/terminal client capabilities are advertised as false, so child agents that depend on them (some Cursor flows) will fail cleanly rather than hang.
• One Pi tool call = one ACP session. No reuse across calls.
• No thinking content piped back — agent_thought_chunk notifications are dropped on the floor.