ACP Editor Adapter

Editor Quick Links

Editor	Guide
Cursor	Cursor Setup
VS Code	VS Code Setup
Zed	Zed Setup
Neovim	Neovim Setup
Vim	Vim Setup

CLI AI Tools: Claude Code | Codex | Gemini

Overview

The ACP (Agent Control Protocol) adapter exposes AgentZero as a full coding agent over JSON-RPC stdio. Unlike MCP which provides individual tools to an external host, ACP runs the complete agentic loop — LLM inference, tool calling, approval flow, and context management — inside AgentZero. The editor sends chat messages; AgentZero drives the model, executes tools, and streams results back.

Starting the Server

az serve

The server reads newline-delimited JSON from stdin and writes responses to stdout.

Protocol

ACP uses a simple request/response format:

{"id": "1", "method": "initialize", "params": {}}

{"id": "1", "success": true, "result": {"name": "agentzero", "version": "0.16.0", "capabilities": ["chat", "tool_call", "session_info", "list_tools", "list_models", "switch_model", "steer", "branch", "tree", "label", "reload", "get_usage"]}}

Available Methods

Method	Description
`initialize`	Returns server info and capabilities
`session_info`	Returns session ID, status, and available tools
`list_tools`	Returns tool definitions
`tool_call`	Execute a tool with arguments
`chat`	Send a chat message (runs full agentic loop)
`list_models`	Returns available models from all configured providers
`switch_model`	Change the active model mid-session
`steer`	Inject a steering message between tool rounds
`branch`	Branch the conversation from a tree node
`tree`	Get the session tree (branching history)
`label`	Label a tree node
`reload`	Reload dynamic tools from the registry
`get_usage`	Get cumulative token usage for the session
`approve_action`	Approve or deny a pending tool call
`cancel`	Cancel/abort the current operation
`shutdown`	Graceful shutdown

Chat

A chat request runs the full agentic loop. AgentZero sends the message to the model, executes any tool calls the model requests (subject to policy and approval), and returns the final response.

{"id": "3", "method": "chat", "params": {"message": "fix the typo on line 12 of README.md"}}

During execution, the server emits notifications for streaming events (see Notifications below). The final response:

{"id": "3", "success": true, "result": {"content": "Fixed the typo on line 12.", "model": "llama3.2", "rounds": 2, "tool_calls": [{"name": "read", "success": true, "output_bytes": 1234}, {"name": "edit", "success": true, "output_bytes": 89}]}}

Tool Calls

Direct tool calls bypass the model and execute a tool immediately:

{"id": "2", "method": "tool_call", "params": {"name": "read", "arguments": {"path": "Cargo.toml"}}}

{"id": "2", "success": true, "result": {"success": true, "output": "[workspace]\n..."}}

All tool calls go through the same session engine as the CLI — policy evaluation, path validation, and audit logging are all active.

Notifications

The server sends AcpNotification messages during chat execution. Notifications are server-initiated and have no id field:

{"notification": "token", "params": {"text": "I'll fix"}}
{"notification": "tool_start", "params": {"tool": "read", "arguments": {"path": "README.md"}}}
{"notification": "tool_result", "params": {"tool": "read", "success": true, "output_bytes": 1234}}
{"notification": "requires_approval", "params": {"request_id": "req-1", "tool": "edit", "arguments": {"path": "README.md", "old_text": "recieve", "new_text": "receive"}}}
{"notification": "context_compacted", "params": {"before": 50, "after": 12}}

Notification	When
`token`	Each streamed token from the model
`tool_start`	A tool call begins
`tool_result`	A tool call completes
`requires_approval`	A tool call needs user approval (respond with `approve_action`)
`context_compacted`	Context window was compacted to fit within model limits
`usage`	Token usage for a round (input/output tokens + session totals)

Steering & Branching

Editors can steer the agent mid-execution, branch conversations, and navigate the session tree.

Steer

Inject a message between tool rounds (the agent processes it on the next LLM call):

{"id": "20", "method": "steer", "params": {"message": "focus on the tests, not the implementation"}}

Branch

Branch the conversation from a prior tree node (truncates history to that point):

{"id": "21", "method": "branch", "params": {"node_id": "n-abc123"}}

Tree

Get the full session tree:

{"id": "22", "method": "tree", "params": {}}

Returns tree (structured data with nodes) and display (ASCII tree rendering).

Label

Label the current tree node:

{"id": "23", "method": "label", "params": {"label": "before refactor"}}

Model Switching

Switch models mid-session without restarting the server:

{"id": "30", "method": "switch_model", "params": {"model": "codellama"}}

Token Usage

Get cumulative token usage for the session:

{"id": "40", "method": "get_usage", "params": {}}

Returns input_tokens, output_tokens, total_tokens, cache_creation_tokens, cache_read_tokens.

Editor Setup

Generate editor-native configuration files with az init --editor:

# VS Code
az init --private --editor vscode

# Cursor
az init --private --editor cursor

# Zed
az init --private --editor zed

This creates the appropriate task or rules files so the editor can launch and communicate with az serve.

ACP vs MCP

	ACP	MCP
Role	Full coding agent	Tool provider
Protocol	Simple JSON-RPC	JSON-RPC 2.0 (standard)
Inference	AgentZero runs the model	Host runs the model
Tool execution	AgentZero decides and executes	Host decides, AgentZero executes
Ecosystem	Custom editors	Claude Code, Cursor, Zed
Tool naming	Internal names (`read`, `list`)	MCP names (`read_file`, `list_directory`)
Use when	Building a custom integration or want AgentZero to drive	Using an existing MCP client

ACP is now the primary and recommended protocol for editor integration. MCP has been moved to an optional feature flag (--features mcp). See ADR 0014.

ACP also supports the generate_tool capability, allowing the agent to create new WASM tools during a session. Generated tools are immediately available for use in the same session.