Agent Client Protocol

// LSP-for-coding-agents · standardize how editors talk to AI agents · use acpx as the headless client

What ACP is

The Agent Client Protocol is a JSON-RPC standard for communication between code editors and AI coding agents. An agent that speaks ACP works in any ACP-capable editor; an editor that speaks ACP works with any ACP-capable agent. Think LSP, but for "edit my code with an LLM" instead of "tell me what's at this cursor."

Maintained by Sergey Ignatov (lead). Spec lives at agentclientprotocol.com; OpenAPI at /api-reference/openapi.json; libraries in Rust, TypeScript, Python, Java, Kotlin.

Why it exists

Three friction points it eliminates:

• N×M integration matrix. Without ACP, every (agent × editor) pair needs a custom integration. With ACP, both sides target the same protocol.
• Tool lock-in. Agents shipped tightly coupled to one editor leave you choosing between "the agent I want" and "the editor I want."
• PTY scraping is brittle. Orchestrators that drive coding agents through pseudo-TTYs fight ANSI escape codes, prompt detection, and stream framing. ACP replaces that with a structured protocol.

The LSP analogy. Before LSP, every editor wrote its own type-checking integration for every language. After LSP, one server per language, one client per editor. ACP applies the same insight to coding agents.

Actors

Transports

ACP uses JSON-RPC 2.0 over one of:

• stdio (default for local agents) — agent runs as a subprocess, client writes requests to its stdin and reads responses from stdout.
• HTTP — for remote agents (RFD: streamable-http-websocket-transport).
• WebSocket — for remote agents needing bidirectional streaming.

┌────────────┐                                     ┌────────────┐
│   Client   │ ── JSON-RPC 2.0 over stdio/ws ──→  │   Agent    │
│ (editor or │ ←── notifications + responses ──   │ (LLM tool) │
│  acpx CLI) │                                     │            │
└────────────┘                                     └────────────┘
       │                                                  │
       └─── manages files/terminals ←─── requests ────────┘

Lifecycle

1. Initialize. Client calls initialize; agent responds with capabilities.
2. Authenticate (optional). Client calls authenticate if the agent requires credentials.
3. Session setup. session/new creates a fresh session; session/load resumes a prior one.
4. Prompt turn. Client calls session/prompt; agent streams session/update notifications, may request file ops, terminal exec, or permission. Eventually the prompt response arrives with a stop reason.
5. Cancel (optional). Client sends session/cancel notification at any time during a turn.
6. Session close (optional but recommended for long-running agents).

Method reference

Agent methods (client → agent)

Client methods (agent → client)

A complete prompt turn

// 1. Client opens session
→ {"jsonrpc":"2.0","id":1,"method":"session/new","params":{"workspace_root":"/Users/me/myproj"}}
← {"jsonrpc":"2.0","id":1,"result":{"session_id":"sess_abc"}}

// 2. Client sends a prompt
→ {"jsonrpc":"2.0","id":2,"method":"session/prompt","params":{
    "session_id":"sess_abc",
    "messages":[{"role":"user","content":[{"type":"text","text":"fix the flaky test"}]}]
  }}

// 3. Agent streams updates back as notifications
← {"jsonrpc":"2.0","method":"session/update","params":{"type":"agent_message_chunk","text":"Looking at "}}
← {"jsonrpc":"2.0","method":"session/update","params":{"type":"tool_call","id":"tc_1","name":"read_file",...}}

// 4. Agent asks the client to read a file
← {"jsonrpc":"2.0","id":"r1","method":"fs/read_text_file","params":{"path":"tests/flaky.test.ts"}}
→ {"jsonrpc":"2.0","id":"r1","result":{"content":"..."}}

// 5. Agent asks permission to write
← {"jsonrpc":"2.0","id":"p1","method":"session/request_permission",
   "params":{"tool":"write_file","path":"tests/flaky.test.ts","diff":"..."}}
→ {"jsonrpc":"2.0","id":"p1","result":{"granted":true}}

// 6. Agent writes
← {"jsonrpc":"2.0","id":"w1","method":"fs/write_text_file",...}

// 7. Agent finishes the turn
← {"jsonrpc":"2.0","id":2,"result":{"stop_reason":"end_turn"}}

Tool calls & updates

Every action an agent takes during a turn — reading a file, running a command, editing code — surfaces to the client as a session/update notification carrying a content block. Content types include text deltas, tool-call markers, plan updates, diffs, and terminal output. Reusing MCP-compatible content shapes where possible; custom types layered on top for agentic UX (notably diffs).

Permissions

Risky operations — writing files, executing shell commands, deleting things — go through session/request_permission. The client decides how to surface the request to the user (modal dialog, auto-approve list, batch confirmation). The agent waits for the response before proceeding.

Why this matters. Permissions in ACP are first-class messages, not policy hacks. An autonomous orchestrator can implement "auto-approve any read; ask once per session for writes; never permit shell" as plain logic in the client. No prompt-engineering required.

Sessions — new, load, list, resume, fork

A session is a turn-by-turn conversation, persisted by the agent. The protocol defines:

• session/new — fresh start
• session/load — resume a stored session by id
• session/list — enumerate available sessions (stabilized)
• session/resume — continue from a checkpoint (stabilized)
• session/close — release server-side state (stabilized)
• session/set_mode — switch agent operating mode (plan / edit / autonomous, agent-defined)
• RFD: session/fork — branch a session for "what if I tried Y instead of X"

acpx — the headless ACP client

openclaw/acpx is a CLI ACP client. It exists so that LLM orchestrators (autoresearch loops, CI bots, Claude Code itself) can drive coding agents over a structured protocol instead of scraping pseudo-TTYs.

One-shot prompt

# talk to Codex over ACP, one prompt, no session
acpx codex "fix the flaky test in tests/auth.spec.ts"

# point at a custom ACP-server binary
acpx --agent ./my-acp-server "summarize this repo"

# run a flow file (multi-step orchestration)
acpx flow run ./repair.flow.ts --input-file ./input.json

Persistent sessions

# list / new / show / history / close
acpx codex sessions new
acpx codex sessions list
acpx codex sessions show sess_abc
acpx codex -s backend "implement token pagination"
acpx codex sessions close sess_abc

Control + config

acpx cancel sess_abc                    # interrupt a running turn
acpx set-mode sess_abc plan             # switch operating mode
acpx set sess_abc max_tokens 4096       # session config option
acpx config show
acpx status

Why use acpx instead of raw stdio

• Persistent session management across CLI invocations
• Prompt queueing — queue messages while a turn is running, fire on completion
• Cooperative cancellation — Ctrl-C maps to session/cancel properly
• Stable fs/* and terminal/* handlers with permission controls and cwd sandboxing
• Adapter wrappers for the 6+ major coding agents — no manual binary plumbing

SDKs

Official libraries (mint a server or client in your language of choice):

• Rust — reference SDK
• TypeScript — what acpx is built on
• Python
• Java · Kotlin
• Community implementations

Extensibility

ACP defines a _meta property on most messages that propagates user data through the protocol. Custom capabilities are negotiated during initialize: each side advertises what it supports, and both sides agree on the intersection. Active RFDs add proxy chains (one ACP server fronting several agents), MCP-over-ACP transport, telemetry export, and elicitation (structured user input).

Integrate with this project

Concrete plays for the Organized AI / clip-pipeline setup:

1. Use acpx as the planner shim. The autoresearch loops in posthog-autoresearch-guide currently fork subprocesses to drive Codex/Claude. Swap that for acpx codex --json, get structured tool calls, log session/update events to PostHog as step.tool_called / step.tool_returned automatically.
2. Run an ACP server for the clip pipeline. Wrap portrait-foreignfilm-clips as an ACP agent that exposes render, retranscribe, upload as tools. Then any ACP client (acpx, Zed, the dashboard) can drive a render with one prompt.
3. Standardize the dashboard's "queue a render" button. Today the pipeline-viz dashboard would need bespoke API calls. With ACP, the dashboard speaks one protocol to any agent — local clip-render agent today, remote one tomorrow.
4. Token Machine routing. Token Machine sits in front of model calls. ACP agents call models. Wire Token Machine as the ACP agent's outbound HTTP transport and you get cost routing for free, with $ai_generation events still flowing through PostHog.

Pitfalls

• Don't confuse ACP with MCP. MCP gives a model access to tools. ACP gives a client access to an agent. They compose (the RFD mcp-over-acp shows the direction), but they're not interchangeable.
• stdio framing. JSON-RPC over stdio uses Content-Length headers (LSP-style). Don't pretty-print, don't add trailing newlines that aren't accounted for in the Content-Length.
• acpx is alpha. 0.6.0 — interfaces will move until stabilization. Pin the version; don't npx acpx@latest in production.
• Permission auto-approval is a footgun. Easy to write { auto_approve: true } in a wrapper and forget. The first time the agent decides to run rm -rf, you'll wish you hadn't. Default-deny shell, allowlist reads.
• Sessions are not free. Many agents persist sessions on disk; session/list and session/close stabilized for a reason. Clean up after CI runs.
• Cancellation is cooperative. session/cancel is a notification, not a forceful kill. The agent must be implemented to check for it. Some don't (or do so only at await points).