wire protocol · adapters · three doors

Wire local CLI coding agents into any client

A zero-dependency Node daemon: implement the client side once and reach any local coding agent (codex, claude, pi, gemini, …) through an adapter. Sessions, approvals, and disconnect-interrupts stay with the agent — the bridge translates, it never becomes a chat window.

Configuration reference → Source on GitHub

v1 wire protocol (frozen) ACP doors (opt-in) agent-side native protocols

three doors

Three doors, all to the same agents

Built-in HTTP+SSE (v1)

POST /turns · GET /sessions · SSE

The minimal wire protocol, always on. Browser extensions, scripts, anything that speaks HTTP. Frozen: additive changes only.

always on · one port per bridge

ACP over WebSocket

ws://host:port/acp

The public door for the ACP ecosystem: acpx, acp-ui, mobile clients connect without learning v1. Opt in per bridge.

set "acp": true

ACP agent over stdio

agent-bridge acp <entry>

Turns one config entry into a spawnable ACP agent — for editors like Zed and vscode-acp that launch agents as local commands.

no port · stdout is protocol only

quick start

Up in four steps

Install

Install the npm package globally — or clone the source and use node cli.mjs where this page says agent-bridge (zero dependencies, no build).
```
npm i -g @xiaohuzai/agent-bridge
```
Create the config

Put an agents.json in the directory you start from. Run agent-bridge serve once without it and it prints the exact copy command for your install:
```
cp /path/to/agents.example.json agents.json
```

Start

One bridge per config entry, each on its own port. Ctrl+C stops all.

$ agent-bridge serve
agent-bridge serve: 4 bridges on http://127.0.0.1
  codex      :3948  (no api key — loopback only)
  claude     :3949  (no api key — loopback only)
  pi         :3950  (no api key — loopback only)
  gemini     :3951  (no api key — loopback only)
Point any wire-protocol client at these addresses.

Connect a client

Point a v1 client at the printed addresses — or have an editor spawn agent-bridge acp claude. That works with no config file at all (it falls back to the built-in default spawn).

Install the agents themselves

The bridge installs nothing: set up and log into codex, claude, pi, gemini separately. A bridge whose agent is missing still starts and answers /health — it fails on its first turn, with an install hint (including the exact command).

npm i -g @openai/codex                                       # codex
npm i -g @anthropic-ai/claude-code @agentclientprotocol/claude-agent-acp  # claude
npm i -g pi-acp                                              # pi (shim; pi itself via its own installer)
npm i -g @google/gemini-cli                                  # gemini

configuration

One config file holds every knob

Ports, apiKey, working directory, codex sandbox and approval policy, the ACP door switch — all in agents.json. The CLI takes only two flags; everything else is a config field.

{
  "bridges": [
    { "name": "codex",  "port": 3948, "apiKey": "",
      "sandbox": "workspace-write", "approval": "on-request" },
    { "name": "claude", "port": 3949, "apiKey": "" },
    { "name": "pi",     "port": 3950, "apiKey": "" },
    { "name": "gemini", "port": 3951, "apiKey": "" }
  ]
}

The full configuration reference lists every field with type, default and allowed values — plus the codex sandbox/approval trade-offs (including how to make codex stop asking).