# pi-acp: an ACP adapter that drives the pi coding agent from an editor

> pi-acp is a small TypeScript process that speaks ACP JSON-RPC 2.0 over stdio to an editor such as Zed and spawns the pi coding agent in rpc mode underneath. It translates tool calls, sessions and context usage, but it labels itself an MVP with breaking changes expected.

**svkozak/pi-acp** — ACP adapter for pi coding agent

- Repository: https://github.com/svkozak/pi-acp
- Stars: 742 · Forks: 211
- Language: TypeScript
- License: MIT
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/svkozak-pi-acp

## A stdio bridge between the pi agent and an ACP client

The problem pi-acp solves is narrow and real. The pi coding agent has its own interface, and editors that speak the Agent Client Protocol cannot talk to it directly. This adapter is the missing pipe: the README states that pi-acp communicates ACP JSON-RPC 2.0 over stdio to an ACP client such as the Zed editor, and that it spawns pi --mode rpc while bridging requests and events between the two.

That design has consequences worth understanding before you install anything. The adapter is a separate process that a client launches, and the actual agent runs as a child process of the adapter. The client never speaks to pi directly, it speaks to pi-acp, and pi-acp translates. Because the transport is stdio and the protocol is JSON-RPC, there is no port to configure and no server to expose, which is convenient for editor integrations that expect a command to spawn. The cost is that the adapter sits in the hot path of every message. Anything it does not translate is simply unavailable to the editor, no matter how capable pi is on the terminal side.

## The adapter translates pi events into ACP shapes

Three translation rules cover most of the traffic. Assistant output is streamed as ACP agent_message_chunk events, which is what lets the editor render a response progressively rather than waiting for a final answer. Pi tool execution is mapped to ACP tool_call and tool_call_update messages, so an editor can display a running tool and then update it when the tool finishes.

The interesting part is the third rule, and it is where this adapter does more than a rename. Relative file paths coming from pi are resolved against the session cwd before they are emitted as ACP tool locations, which is what makes follow-along features work in clients like Zed, where the editor can open the file being touched. Tool call locations are surfaced when the client supports opening the referenced file or context. On top of that, for the edit tool pi-acp snapshots the file before the tool runs and emits an ACP structured diff with oldText and newText on completion when possible, and it attempts to infer a one-based line number from a unique oldText match in the pre-edit snapshot. Both are best-effort, and the wording in the README about what happens when possible makes that explicit.

## Session reattachment depends on a small mapping file

Pi keeps its own session records in ~/.pi/agent/sessions/..., and pi-acp does not replace that store. Instead it keeps a small mapping file at ~/.pi/pi-acp/session-map.json, and the purpose of that file is narrow: it lets session/load reattach to a previous pi session file. The ACP client can therefore resume a conversation that pi already had on disk, and the README notes that sessions can be resumed both in pi and in the ACP client, with session history in Zed supported starting with Zed v0.225.0.

The two-level design is sensible because it leaves pi as the owner of session data. The price is a dependency on the internal layout of pi's session directory, which is a private convention rather than a published interface, so a change to how pi stores sessions could quietly break reattachment in the editor. The mapping file also means the adapter keeps state outside the editor, which is worth knowing when you move a workspace between machines or when you debug a session that the client cannot find. The README does not document a repair procedure for a stale session-map.json, so a mismatch there is a problem you would have to resolve by inspection.

## Four ways to install, from registry entry to local build

Before anything else, pi itself has to be present, because the adapter runs the pi executable. The README asks you to install it globally and to use pi v0.81.0 or later on your PATH, with Node.js 22+ listed under prerequisites, and to configure pi separately for your model providers and API keys. The adapter package is TypeScript, ESM, and its package.json declares a bin entry named pi-acp pointing at dist/index.js.

```bash
npm install -g @earendil-works/pi-coding-agent
```

```bash
npm install -g pi-acp
```

The four installation paths differ in how much they commit you to a version. The registry route is the tidiest: in Zed you run the zed: acp registry command and pick the pi ACP adapter, and Zed writes the agent server configuration into settings.json itself and keeps it up to date, using a registry type entry for the adapter. The npx route skips a global install and always loads the latest version, which is convenient for a trial and unpleasant for a team that wants a pinned adapter.

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

A global install puts pi-acp on your PATH and makes the command simply pi-acp, and building from source runs npm install plus npm run build and points the client at dist/index.js with node.

## Slash commands are curated, and two of them are missing

The adapter loads file-based slash commands that follow pi conventions, from user command files under ~/.pi/agent/prompts and project command files under <cwd>/.pi/prompts, following pi's own convention of nested markdown files. It adds its own small set of built-in commands aimed at headless and editor use, and it surfaces skill commands as /skill:skill-name when skills are enabled in pi settings.

The built-in list is where the documentation gets honest. /compact accepts optional custom instructions, /autocompact toggles automatic compaction, /export writes the current session to HTML in the session cwd, /session shows session stats covering tokens, messages, cost and the session file, /name sets the session display name, /queue sets the pi queue mode, /changelog prints the installed pi changelog on a best-effort basis, and /steering and /follow-up map to the equivalent pi modes. Two entries are explicitly not implemented: /model, where the README points you at the model selector UI in Zed, and /clear, where it points you at the client new command. Slash commands supplied by pi extensions are also not currently supported. If your workflow leans on extension commands, that is the gap to check first.

## Context usage reporting is gated on a specific pi version

The adapter reports pi's real context occupancy to the client as an ACP usage_update event after each turn, on session/new, on session/load, and after a model switch. The data comes from pi's get_session_stats response, and the field is contextUsage.

Two conditions shape how much you can rely on that. The README says a pi version whose get_session_stats response includes contextUsage is required, and otherwise no usage is reported at all, so an old pi gives you a working adapter with a permanently blank indicator. There is also a startup hiccup: right after compaction, pi may not have a trustworthy token count yet, so the client keeps the previous value until the next model response. That behaviour is a reasonable choice, since a wrong number is worse than a stale one, but it means the meter can disagree with reality for a turn or two after a compaction.

The same section covers how much of pi the editor can see. pi-acp emits a startup info block into the session with the pi version, context, skills, prompts and extensions, similar to what pi shows in the terminal, and you can silence it with quietStartup: true in pi settings at ~/.pi/agent/settings.json or <project>/.pi/settings.json. Even then, a New version available message still appears when the installed pi is outdated.

## Registry authentication is delegated to a pi terminal login

One workflow is specific enough to deserve its own note, because it is the point where the adapter steps aside. pi-acp supports Terminal Auth for the ACP Registry, and in Zed that shows as an Authenticate banner that launches pi in a terminal for interactive login and setup.

```bash
pi-acp --terminal-login
```

Your ACP client can also trigger this on its own, based on the authMethods the agent advertises, so a client that understands the registry can start the flow without the user copying a command. The design is worth noticing for a reason beyond convenience. Authentication is not implemented inside the adapter, and the adapter does not hold provider credentials. Pi is already configured separately for model providers and API keys, so the terminal login hands control to the tool that already knows the credentials. The one requirement is that a human is present at a terminal, which rules the flow out for a fully unattended editor session that expects to authenticate itself.

The result is a split of responsibilities that is easy to reason about. The adapter handles protocol translation and editor-facing features, and pi keeps everything to do with the model conversation, including credentials, session files and skills. The trade-off is that the two pieces have to be installed and upgraded as a pair rather than as one unit.

## An MVP with expected breaking changes and one favoured client

The README is unusually direct about the maturity of this project. It calls pi-acp an MVP-style adapter intended to be useful today and easy to iterate on, notes that some ACP features may be not implemented or are not supported, and says to expect some minor breaking changes. Development is centered around support for the Zed editor, and other clients may have varying levels of compatibility. That is a strategy, and it makes sense for a solo-maintained adapter, but it also means the ACP surface you can count on is the one Zed happens to need.

The version numbers reinforce the point. The published releases are v0.0.32, v0.0.33 and v0.0.34, with v0.0.34 dated 2026-09-24, and the last push was on 2026-10-06. A 0.0.x line is a promise of instability, and the project's own licence, MIT, and its public publish config with provenance enabled are the parts of the setup that are settled. One more practical point: the adapter is spawned by the editor, so the adapter and the pi executable have to agree on versions in ways the README only partly covers, and the fact that pi itself must be v0.81.0 or later is a hard floor rather than a suggestion.

## Conclusion

pi-acp is worth adopting if you already run the pi coding agent and want it inside Zed, and you are willing to track a 0.0.x package that expects minor breaking changes and currently centres development on one client. Do not adopt it as a general ACP compatibility layer for other editors, since the README says other clients may have varying levels of compatibility. Before wiring it into daily work, install the pi executable from npm so the adapter can spawn pi --mode rpc, confirm your pi version reports contextUsage in get_session_stats if you rely on the usage indicator, and expect /model and /clear to remain unimplemented in the client.

## FAQ

### What does pi-acp actually do at runtime?

The README states that pi-acp communicates ACP JSON-RPC 2.0 over stdio to an ACP client such as Zed and spawns pi --mode rpc, bridging requests and events between the two. It maps pi tool execution to ACP tool_call and tool_call_update events.

### How do I install pi-acp for use in Zed?

You can add it through the ACP Registry inside Zed with the zed: acp registry command, install it globally with npm install -g pi-acp, run it through npx, or build it from source. Whatever the route, pi itself must be installed and available on your PATH as v0.81.0 or later.

### Does pi-acp work with editors other than Zed?

The README says development is centered around Zed editor support and that other clients may have varying levels of compatibility. It also lists a set of features marked as Zed specific, such as the startup info block and session history support in Zed v0.225.0 and later.

### Why is the context usage indicator empty in my client?

Context usage is reported from the get_session_stats response and requires a pi version whose response includes contextUsage, otherwise no usage is reported. Right after compaction pi may not have a trustworthy token count yet, and the client keeps the previous value until the next model response.

## Sources

- [Issues](https://github.com/svkozak/pi-acp/issues)
- [License: MIT](https://github.com/svkozak/pi-acp/blob/main/LICENSE)
- [README](https://github.com/svkozak/pi-acp/blob/main/README.md)
- [Releases](https://github.com/svkozak/pi-acp/releases)
- [svkozak/pi-acp on GitHub](https://github.com/svkozak/pi-acp)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/svkozak-pi-acp