pi-acp

ACP (Agent Client Protocol) adapter for pi coding agent (fka shitty coding agent).

pi-acp communicates ACP JSON-RPC 2.0 over stdio to an ACP client (e.g. Zed editor) and spawns pi --mode rpc, bridging requests/events between the two.

Status

This is an MVP-style adapter intended to be useful today and easy to iterate on. Some ACP features may be not implemented or are not supported (see Limitations). Development is centered around Zed editor support, other clients may have varying levels of compatibility.

Expect some minor breaking changes.

Features

• Streams assistant output as ACP agent_message_chunk
• Maps pi tool execution to ACP tool_call / tool_call_update
  • For edit, pi-acp snapshots the file before the tool runs and emits an ACP structured diff (oldText/newText) on completion when possible
• Session persistence
  • pi stores its own sessions in ~/.pi/agent/sessions/...
  • pi-acp stores a small mapping file at ~/.pi/pi-acp/session-map.json so session/load can reattach to a previous pi session file
• Slash commands
  • Loads file-based slash commands compatible with pi’s conventions
  • Adds a small set of built-in commands for headless/editor usage
  • Supports skill commands (if enabled in pi settings, they appear as /skill:skill-name in the ACP client)
• Skills are loaded by pi directly and are available in ACP sessions
• (Zed) pi-acp emits “startup info” block into the session (pi version, context, skills, prompts, extensions - similar to pi in the terminal). You can disable it by setting quietStartup: true in pi settings (~/.pi/agent/settings.json or <project>/.pi/settings.json). When quietStartup is enabled, pi-acp will still emit a 'New version available' message if the installed pi version is outdated.
• (Zed) Session history is supported in Zed starting with v0.225.0. Session loading / history maps to pi's session files. Sessions can be resumed both in pi and in the ACP client.

Prerequisites

Make sure pi is installed

npm install -g @mariozechner/pi-coding-agent

• Node.js 22+
• pi installed and available on your PATH (the adapter runs the pi executable)
• Configure pi separately for your model providers/API keys

Install

Add pi-acp to your ACP client, e.g. Zed

Using ACP Registry in Zed or other clients that support it:

In Zed launch the registry with zed: acp registry command and select pi ACP adapter from the list. This will automatically add the agent server configuration to your settings.json and keep it up to date:

  "agent_servers": {
    "pi-acp": {
      "type": "registry",
    },
  }

Using with npx (no global install needed, always loads the latest version):

Add the following to your Zed settings.json:

  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "npx",
      "args": ["-y", "pi-acp"],
      "env": {}
    }
  }

Global install

npm install -g pi-acp

  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "pi-acp",
      "args": [],
      "env": {}
    }
  }

From source

npm install
npm run build

Point your ACP client to the built dist/index.js:

  "agent_servers": {
    "pi": {
      "type": "custom",
      "command": "node",
      "args": ["/path/to/pi-acp/dist/index.js"],
      "env": {}
    }
  }

Slash commands

pi-acp supports slash commands:

1) File-based commands (aka prompts)

Loaded from:

• User commands: ~/.pi/agent/prompts/**/*.md
• Project commands: <cwd>/.pi/prompts/**/*.md

2) Built-in commands

• /compact [instructions...] – run pi compaction (optionally with custom instructions)
• /autocompact on|off|toggle – toggle automatic compaction
• /export – export the current session to HTML in the session cwd
• /session – show session stats (tokens/messages/cost/session file)
• /name <name> – set session display name
• /queue all|one-at-a-time – set pi queue mode (unstable feature)
• /changelog – print the installed pi changelog (best-effort)
• /steering - maps to pi Steering Mode, get/set
• /follow-up - pats to pi Follow-up Mode, get/set

Other built-in commands:

• /model - maps to model selector in Zed
• /thinking - maps to 'mode' selector in Zed
• /clear - not implemented (use ACP client 'new' command)

3) Skill commands

• Skill commands can be enabled in pi settings and will appear in the slash command list in ACP client as /skill:skill-name.

Note: Slash commands provided by pi extensions are not currently supported.

Authentication (ACP Registry support)

This agent supports Terminal Auth for the ACP Registry. In Zed, this will show an Authenticate banner that launches pi in a terminal. Launch pi in a terminal for interactive login/setup:

pi-acp --terminal-login

Your ACP client can also invoke this automatically based on the agent's advertised authMethods.

Development

npm install
npm run dev        # run from src via tsx
npm run build
npm run lint
npm run test

Project layout:

• src/acp/* – ACP server + translation layer
• src/pi-rpc/* – pi subprocess wrapper (RPC protocol)

Limitations

• No ACP filesystem delegation (fs/*) and no ACP terminal delegation (terminal/*). pi reads/writes and executes locally.
• MCP servers are accepted in ACP params and stored in session state, but not wired through to pi (see why). If you use pi MCP adapter it will be available in the ACP client.
• Assistant streaming is currently sent as agent_message_chunk (no separate thought stream).
• Queue is implemented client-side and should work like pi's one-at-a-time
• ~~ACP clients don't yet suport session history, but ACP sessions from pi-acp can be /resumed in pi directly~~

License

MIT (see LICENSE).