claude-acp-server

Agent Client Protocol (ACP) bridge for Claude Code — run JSON-RPC over stdio (default) or WebSocket, and drive the claude CLI in --print mode with stream-json output mapped to ACP session/update notifications.

This project implements the agent side using the official @agentclientprotocol/sdk, so it tracks the Agent Client Protocol (protocol version 1).

What is this?

Editors that speak ACP (for example Zed) expect a subprocess or socket that exchanges newline-delimited JSON-RPC messages. This server is that subprocess: it translates ACP methods (initialize, session/new, session/prompt, …) into Claude Code invocations with -p / --resume, streams NDJSON from --output-format stream-json --verbose --include-partial-messages, and forwards text and tool events to the client as session/update notifications.

You need a working Claude Code install and authentication (claude on PATH, or npx @anthropic-ai/claude-code, per your setup).

Install

cd claude-acp-server
npm install
npm run build

Quick start (stdio)

npm start

The process reads JSON-RPC from stdin and writes responses to stdout. Log lines go to stderr (ACP requires stdout to contain only protocol messages).

When the package is installed globally or linked from a clone (npm link after npm run build), the same entry is available as the claude-acp-server command (see bin in package.json).

WebSocket

npm run start:ws -- --port 3000 --host 0.0.0.0

The WebSocket transport uses the same newline-delimited JSON-RPC framing as stdio (one JSON object per message). A single connection can handle multiple ACP sessions via session/new and session/load, the same as stdio.

CLI flags

Each session/new still sends its own absolute workspace cwd; that value is what Claude Code uses when spawned, not only this flag.

Editor configuration

Zed (settings.json)

Use the absolute path to the built dist/index.js (or node + path to the repo):

{
  "assistant": {
    "acp": {
      "servers": [
        {
          "name": "Claude Code",
          "command": "node",
          "args": ["/absolute/path/to/claude-acp-server/dist/index.js"],
          "env": {
            "CLAUDE_CODE_ALLOWED_TOOLS": "Read,Grep,Bash"
          }
        }
      ]
    }
  }
}

VS Code

Install an ACP client extension (for example the ACP Client from the marketplace), then point it at the same node dist/index.js command.

Environment variables

Optional file: ~/.claude-acp/config.json may define allowedTools and disallowedTools (used when the env vars are unset). See .env.example.

Custom Node runner (advanced)

If CLAUDE_CODE_BIN is set to a .mjs / .js / .cjs file, the server runs node <that-file> -p … with the same flags as the real CLI. This is useful for tests or custom wrappers.

Repository layout

claude-acp-server/
├── src/
│   ├── index.ts              # CLI entry, exports
│   ├── server.ts             # ACPServer class
│   ├── config.ts             # Env, ~/.claude-acp/config.json, CLI flags
│   ├── claude-agent.ts       # ACP Agent → Claude Code
│   ├── session-store.ts      # Session metadata + transcripts
│   ├── claude/
│   │   ├── run-claude.ts     # Spawn CLI, NDJSON stdout
│   │   ├── stream-json.ts    # Claude lines → session/update
│   │   └── prompt-text.ts    # Content blocks → prompt string
│   └── transports/
│       ├── stdio.ts
│       └── websocket.ts
├── tests/
├── dist/                     # `npm run build` (removed by `npm run clean`)
├── tsconfig.json
├── vitest.config.ts
├── .env.example
├── .gitignore
├── package.json
├── README.md
└── LICENSE

Architecture

Editor (ACP client)
    │  JSON-RPC (NDJSON over stdio or WebSocket)
    ▼
@agentclientprotocol/sdk  →  ClaudeAgent  →  spawn Claude Code (-p, stream-json)
    │                                              │
    └──────── session/update notifications ◄────────┘

• Sessions: Each ACP sessionId is a UUID. The first prompt uses --session-id; later prompts use --resume with the same id.
• Transcripts: User and assistant text are appended under ACP_SESSION_DIR so session/load can replay history via session/update (when supported by the client).

Implemented ACP surface

Tool permission prompts are handled inside Claude Code; this bridge does not forward interactive permission UI to the editor unless extended to do so.

Programmatic API

import { ACPServer } from "claude-acp-server";

const server = new ACPServer({
  mode: "stdio",
  cwd: "/path/to/project",
  allowedTools: ["Read", "Grep"],
});

await server.start();

ACPServer.start() applies cwd with process.chdir (same as the CLI --cwd flag).

Testing

npm test

Full compile + test (recommended before commits or CI):

npm run build && npm test

Tests cover CLI/config parsing, stream-json mapping, prompt text from content blocks, and an end-to-end ACP handshake using a tiny fake Claude script (no API or claude binary required).

Development: npm run clean deletes dist/; npm run dev runs the TypeScript entry with watch. Vitest runs test files sequentially so process.chdir in config tests does not race other suites.

Docker (example)

FROM node:22-alpine
RUN npm install -g @anthropic-ai/claude-code
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["node", "dist/index.js", "--mode", "ws", "--host", "0.0.0.0", "--port", "3000"]

References

• Agent Client Protocol
• TypeScript SDK
• Claude Code documentation

License

See LICENSE (MIT).