# claude-agent-acp: running the Claude Agent SDK inside any ACP client

> The @agentclientprotocol/claude-agent-acp package is a TypeScript ACP agent that wraps the official Claude Agent SDK, so editors like Zed and JetBrains IDEs can drive Claude Code sessions over a protocol instead of a terminal. It installs from npm, requires Node 22 or newer, and its most interesting behaviour is gated on capability negotiation.

**agentclientprotocol/claude-agent-acp** — Use Claude Agent SDK from any ACP client

- Repository: https://github.com/agentclientprotocol/claude-agent-acp
- Stars: 2,597 · Forks: 412
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-28 · Updated: 2026-09-28 · Language: en
- Canonical page: https://hysenlabs.com/projects/agentclientprotocol-claude-agent-acp

## The gap between a terminal coding agent and an editor that speaks ACP

The Claude Agent SDK gives you programmatic access to Claude Code style sessions, but that access arrives as a library, not as something an editor can render. Editors that implement the Agent Client Protocol expect an agent process on the other end that speaks ACP: initialization, session creation, streamed tool calls, permission requests, file changes. claude-agent-acp is the adapter that sits between the two. It is published as @agentclientprotocol/claude-agent-acp, its package description calls it "An ACP-compatible coding agent powered by the Claude Agent SDK (TypeScript)", and the author field in package.json is Zed Industries, which fits the ACP origin story. The audience is narrow and specific: developers whose editor or IDE already has an ACP client, and who want the Claude Agent SDK behind it rather than a separate chat integration. If your tool has no ACP client, this package has nothing to attach to.

## What the adapter actually negotiates before anything is rendered

The README lists the surface the adapter supports: context @-mentions, images, tool calls with permission requests, TODO lists, nested subagent transcripts, interactive and background terminals, custom slash commands, and client MCP servers. Most of that maps onto ordinary ACP traffic. The more revealing part is the AIR extension set, documented in docs/air-extensions.md, which the adapter exposes through `_meta` keys and opt-in capabilities: a diff patch extension for compact file changes, a goal extension under `_meta.jetbrains.air.goal` for session-scoped long-running goals, a session failure extension for structured errors, recovery and warnings, a recommended config value extension for concrete model and effort defaults, and a permission extension covering presentation, editable choices and durable effects. Subagents are the clearest example of the negotiation model. The README states that subagents are exposed only after bilateral capability negotiation, and that until the released ACP SDKs preserve the draft `clientCapabilities.subagents` field, a supporting client may advertise `nativeSubagentSessions` in `_meta.jetbrains.air.capabilities`. The adapter mirrors the capability in its initialize response, and the canonical field takes precedence once it is available. Without either client signal, Agent and Task lifecycle keeps its legacy ordinary ACP tool-call representation and child interactions stay on the root session. Clients using the historical `_meta["subagent-transcript"]` capability or the `forwardSubagentText` session option keep the flattened child transcript behaviour. That is a deliberate compatibility ladder, and it means the same adapter renders differently in two clients that both claim ACP support.

## Installing claude-agent-acp and pointing a client at it

The package ships a binary named claude-agent-acp, mapped in package.json to dist/index.js, and it requires Node 22 or newer per the engines field. Install it globally if you want the binary on your PATH, or install it as a dependency of the client configuration that will launch it. The README gives this command for the released package:

```bash
npm install @agentclientprotocol/claude-agent-acp
```

If you want changes that have landed on main but are not in a release yet, the README points at the preview channel: every push to main publishes one. That is a separate install target, not a version tag you append to the stable package:

```bash
npm install @agentclientprotocol/claude-agent-acp@preview
```

The repository also ships runnable examples. examples/simple-client.ts is wired to a script in package.json, so you can exercise the adapter without configuring an editor first:

```bash
npm run example:simple-client
```

That script runs node with --experimental-strip-types and --disable-warning=ExperimentalWarning against the TypeScript example directly. The second example, examples/steering.ts, is not exposed as an npm script in package.json, so running it means invoking node with the same flags yourself. For a real client, the connection detail the client needs is the binary path or the package name plus the claude-agent-acp command; the README does not document a configuration file format of its own, so the launch configuration lives in the client, not in this package. There is no Homebrew formula mentioned anywhere in the README or package.json, despite that being a common search for this project.

## Where the adapter is the wrong layer

The first limitation is structural: this is a bridge, and a bridge inherits both banks. If the Claude Agent SDK changes a session concept, the adapter has to translate it; if an ACP client implements only part of the protocol, the adapter falls back. The subagent behaviour described above is the concrete cost. A client that has not adopted the draft field or the JetBrains `_meta` capability does not get native subagent sessions; it gets Agent and Task calls represented as ordinary ACP tool calls with child interactions on the root session. That is not a bug, but it is a different product experience, and it is decided by the client, not by anything you configure in this package. The AIR extensions have the same shape: the diff patch extension is described as negotiated, and the session failure and recommended config value extensions are explicitly opt-in. A client that opts into none of them gets a plainer session. The second limitation is the runtime floor. Node 22 or newer is not a suggestion; it is in engines, and anything older is outside the supported range. The third is scope. This package is an agent for ACP clients. If you want a terminal coding agent, you already have one without an adapter in between. If your editor has no ACP client, nothing here helps, and the README does not describe a standalone UI.

## How this differs from driving the Claude Agent SDK directly

The obvious alternative is to use the Claude Agent SDK yourself and render its output in your own tool. That gives you full control over the session model and no protocol translation layer, but you also own every piece the adapter already handles: permission prompts presented as editable choices, diff patches compressed through the AIR extension, TODO lists, terminal handling, nested subagent transcripts, MCP server wiring, slash commands. The adapter exists because that list is long and because ACP clients already know how to render it. The trade is the opposite of what people usually assume: going direct is more work, not less, unless your requirements are narrow enough that you never need the rendering contract. A second alternative is a client-specific Claude integration. Those tend to bind you to one editor and one release cadence. The adapter's value is that the same agent process serves any client that implements ACP and negotiates the extensions it wants. The cost is that your feature set is the intersection of what the adapter supports and what your client negotiates, which is why the capability ladder in the README matters more than the feature list.

## Maintenance, releases and what the Apache-2.0 licence means here

The last push to the repository was on 2026-09-28, the same day as the v0.82.0 release, and the repository is not archived. The release history shows a fast cadence: v0.82.0 on 2026-09-28, v0.81.2 on 2026-09-24, v0.81.1 on 2026-09-23. Release automation is visible in the repository layout, with release-please-config.json and .release-please-manifest.json at the top level, plus a scripts/release-preflight.sh wired to the release:preflight npm script. That combination is a real upgrade cost signal: frequent releases plus automated changelog and manifest updates means version bumps arrive often, and the preview channel publishes on every push to main, so anyone tracking preview is tracking an unreleased state by definition. The licence is Apache-2.0, and the README states the project does not require a Contributor License Agreement. Instead, contributions are accepted under terms quoted in the README: by contributing, you agree your contributions are licensed under Apache License 2.0, you affirm you have the legal right to submit the work, you are not including code you lack rights to, and you understand contributions are made without requiring a CLA. For adopters, Apache-2.0 is a permissive licence with an explicit patent grant, but whether it fits your distribution model is a question for your own counsel, not something this article can settle. The npm package is published with public access and the files list includes dist/, README.md, LICENSE and package.json, so the published artifact is the compiled output plus documentation.

## Conclusion

Adopt claude-agent-acp if you already run an ACP client and want Claude Agent SDK sessions inside it, with tool permission prompts, diff patches and subagent transcripts handled through the protocol. Do not adopt it if your editor speaks no ACP, or if you need a stable subagent contract today: the README states that subagent sessions are exposed only after bilateral capability negotiation, and clients without a signal keep the legacy flattened representation. Before wiring it into a team workflow, verify three things against your own client build: that it advertises nativeSubagentSessions or the canonical clientCapabilities.subagents field, that it honours the AIR diff patch extension, and that your Node runtime is at least 22, since the package engines field sets that floor.

## FAQ

### What is claude-agent-acp?

It is an ACP-compatible coding agent built on the Claude Agent SDK, written in TypeScript and published as @agentclientprotocol/claude-agent-acp. It lets ACP clients drive Claude Agent SDK sessions instead of talking to the SDK directly.

### What is an ACP agent?

An ACP agent is a process that speaks the Agent Client Protocol, so a compatible client can initialize a session, receive streamed tool calls and file changes, and issue permission requests. claude-agent-acp implements that role on top of the Claude Agent SDK.

### What are ACP clients?

ACP clients are the applications on the other side of the protocol, such as the editors and IDEs that launch an agent and render its sessions. The README describes behaviour that depends on what a given client negotiates, including the AIR extensions and native subagent sessions.

### How do I install claude-agent-acp?

Install it from npm with npm install @agentclientprotocol/claude-agent-acp, or use the @preview tag to try changes that have landed on main but are not released yet. The package requires Node 22 or newer.

### How do I use claude-agent-acp?

Point an ACP client at the claude-agent-acp binary, which package.json maps to dist/index.js. To try it without an editor, the repository provides examples/simple-client.ts, runnable through the example:simple-client npm script.

## Sources

- [agentclientprotocol/claude-agent-acp on GitHub](https://github.com/agentclientprotocol/claude-agent-acp)
- [Issues](https://github.com/agentclientprotocol/claude-agent-acp/issues)
- [License: Apache-2.0](https://github.com/agentclientprotocol/claude-agent-acp/blob/main/LICENSE)
- [README](https://github.com/agentclientprotocol/claude-agent-acp/blob/main/README.md)
- [Releases](https://github.com/agentclientprotocol/claude-agent-acp/releases)

---

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