// LLM knowledge base for the Agent Client Protocol + acpx (openclaw)
#id, a type badge, a one-paragraph description, and chips linking to what it depends on and what depends on it. Open any link in a new tab — anchor navigation preserves context. Load this page as context for an LLM working with ACP rather than crawling the spec; it's the distilled graph of what exists and how it connects.
┌────────────────────────────────────────────┐
│ initialize → authenticate? → session/new │
└────────────────────┬───────────────────────┘
▼
┌─────────┐ session/prompt ┌─────────┐
│ Client │ ───────────────────────────▶│ Agent │
│ (editor │ ◀─── session/update (n) ─── │ (LLM) │
│ / acpx)│ ◀─── fs/* terminal/* req ── │ │
│ │ ───── responses ─────────▶ │ │
│ │ ───── session/cancel (n) ─▶ │ │
└─────────┘ └─────────┘
│
▼
result {stop_reason}
transports: stdio (default · local) · HTTP · WebSocket (RFD)
Program that uses generative AI to autonomously modify code. Implements the agent-side methods and emits session/update notifications during a turn.
Editor or orchestrator that drives the agent. Owns the workspace, files, and terminals; renders updates to the user. Examples: VSCode, Zed, Neovim, JetBrains, acpx.
Default for local agents. Agent runs as subprocess; client writes JSON-RPC to its stdin, reads from stdout. Uses LSP-style Content-Length framing.
For remote agents. RFD: streamable-http-websocket-transport. Allows hosted/cloud agents to participate in ACP without local subprocess.
For remote agents needing bidirectional streaming (server-pushed session/update notifications). Same RFD as HTTP transport.
Spec uses JSON-RPC 2.0 for both methods (request/response) and notifications (one-way). Content-Length framing on stdio.
Handshake. Client calls initialize; agent responds with capabilities and protocol version. Optional authenticate follows.
Client opens a session via session/new or resumes via session/load. A session is the unit of conversation persistence.
Client sends session/prompt. Agent streams session/update notifications, may request file ops + terminal exec + permission. Turn ends when agent returns response with stop_reason.
Client sends session/cancel notification at any time during a turn. Cooperative — agent must check and exit gracefully.
Release server-side state. Stabilized announcement: session-close-stabilized.
First call after transport connects. Exchanges protocol version + capabilities. Optional metadata via implementation-information announcement.
Optional auth flow before sessions. RFD: auth-methods covers approaches (API key, OAuth, bearer).
Create a fresh conversation session. Returns session_id. Params include workspace_root and optional config.
Resume a previously-created session by id. Pairs with session/list for discovery.
Send a user message and receive the turn's stop reason. Streaming progress arrives via session/update notifications between request and response.
Switch agent operating mode (plan / edit / autonomous — agent-defined enum). Tells the agent how aggressive to be.
Interrupt the current turn. Notification only — no response expected. Cooperative: agent must check and stop voluntarily.
Enumerate sessions the agent has stored. Stabilization announcement: session-list-stabilized.
Streaming progress from agent to client during a turn. Carries text deltas, tool calls, plan updates, diffs, terminal output. Most-emitted message in the protocol.
Agent asks user (via client) to approve a risky operation. Client decides UX (modal, batch, allowlist).
Agent asks client to read a file from the workspace. Client may apply path sandboxing.
Agent asks client to write a file. Typically gated by session/request_permission first.
Agent asks client to spawn a shell session. Client returns a terminal handle for follow-up calls.
Read terminal output by handle. May stream or be pull-based depending on agent.
Block until the running command exits. Returns exit code.
Release the terminal handle and free associated resources.
The unit of conversation persistence. Identified by session_id. Can be new, loaded, listed, resumed, closed, set into a mode, and (RFD) forked.
Discriminated union of message content. Types: text (Markdown by default), image, tool_call, tool_result, diff, plan_update, terminal_output. MCP-compatible where overlapping; ACP adds diff + plan.
Carried inside session/update. Reports an action the agent took: name, args, result, status. Can be reported in flight (status=running) and updated to status=completed/failed.
Structured execution plan the agent shares with the client mid-turn. Steps with status — lets the UI render a checklist that updates live.
Negotiated during initialize. Each side declares what it supports; both sides agree on the intersection. The mechanism by which the protocol is extensible.
Returned in the session/prompt response. Tells the client why the turn ended: end_turn, max_tokens, cancelled, error, etc.
Operating modes the agent advertises. Common values: plan (think only), edit (read + suggest), autonomous (read + write + shell).
Per-session settings (max tokens, model, system prompt, etc.). Agents declare available options; clients select. Stabilized.
Optional property on most messages. Carries user data through the protocol unmodified. RFD: meta-propagation defines which messages must propagate it.
How agents report actions to clients. Reports in-flight (status updates) and final result. Drives the live activity view in editors.
Filesystem access methods (fs/read_text_file, fs/write_text_file). Defines how the agent reads/writes within the workspace via the client.
Terminal lifecycle methods (terminal/create · output · wait_for_exit · kill · release). Defines how the agent runs shell commands through the client.
Agents advertise slash commands the client can surface (e.g. /run-tests). Lets editor UI populate quick actions without bespoke code per agent.
First-class messages (session/request_permission) rather than policy hacks. Client decides UX; auto-approve allowlists are plain logic. Default-deny shell, allowlist reads is a sane baseline.
Capability negotiation in initialize + _meta propagation on messages. New features ship as RFDs, get implemented by both sides, then announced as stabilized.
MCP gives a model access to tools. ACP gives a client access to an agent. They compose — RFD mcp-over-acp shows the direction — but they're not interchangeable.
The cited inspiration. LSP standardized "tell me what's at this cursor"; ACP standardizes "edit my code with an LLM." Same JSON-RPC + stdio + Content-Length framing.
Discovery + installation mechanism for ACP agents. Stabilized announcement: acp-agent-registry-stabilized.
Collaborative groups that drive specific areas (e.g. transports working group). Anyone can start one; outputs feed back into RFDs.
Request for Dialog — the protocol's change-proposal mechanism. RFDs go through draft → discussion → implementation → stabilization announcements.
OpenClaw's headless CLI ACP client. TypeScript/Node, MIT, alpha v0.6.0. Designed so orchestrators can talk to coding agents over a structured protocol instead of PTY scraping.
sessions {new|list|show|history|ensure|close} · prompt / exec · cancel · set-mode · set <k> <v> · flow run <file> · config {show|init} · status.
Built-in wrappers for codex, claude, gemini, cursor, pi, openclaw. Auto-downloaded via npx on first use. Bypasses bespoke binary plumbing per agent.
Used by acpx and most editor extensions. Ergonomic for both client and server roles.
HTTP and WebSocket transports for remote agents. Driven by the transports working group.
Discovery + installation registry for ACP agents. Stabilized.
MCP transport carried over ACP. Lets ACP agents broker MCP servers to the client uniformly.
Branch a session — "what if I tried Y instead of X." Useful for autoresearch loops exploring alternatives.
Active session closure. Releases agent-side state. Stabilized.
Cancellation semantics for in-flight requests beyond session/cancel.
Structured user input — let agents request schema-typed answers from the user mid-turn (form-style), not just free text.
Agent extension via proxies — one ACP server fronting several agents transparently.
Telemetry capabilities — agents export structured perf/cost/quality signals to clients.
Multiple workspace roots — for monorepo / multi-repo setups where one session spans several trees.
Configurable LLM provider per session — useful for routing through Token Machine or self-hosted endpoints.
Edit-recommendation feature — agent proactively suggests the next change after one is accepted.
Representation for deleted-file diffs — current diff types assume content; delete needs explicit handling.
The canonical spec, RFDs, libraries, and announcements live at agentclientprotocol.com.
Machine-readable API description for ACP. Useful for codegen and validation.
The narrative how-to companion to this wiki. Walks through what/why/lifecycle/example/integrate.
How ACP fits with the portrait-captions + pipeline-viz project — wrapping portrait-foreignfilm-clips as an ACP agent so any client can drive renders with one prompt.
Sergey Ignatov — lead maintainer (announced). Governance docs at /community/governance.