What is ACP? Claude Code, Codex, Cursor and Grok Build
By Flavio
ACP is how an editor drives a coding agent over stdin and stdout. Cursor and Grok Build speak it. Claude Code and Codex document a different programmatic path.
ACP (Agent Client Protocol) is how an editor drives a coding agent as a child process. The editor writes JSON-RPC on the agent’s stdin. The agent writes responses on stdout. You stay in the editor. The agent still does the file and shell work.
It is not MCP. MCP is how the agent calls a tool server. ACP is how the editor calls the agent. Headless mode is the other programmatic path: one prompt in, one result out, no editor in the middle.
How ACP works
The editor spawns the agent binary with an ACP argument. Messages are JSON-RPC 2.0, one JSON object per line. Logs can go to stderr, so they stay out of the protocol stream.
A typical session has the same shape on the clients that document it. The client sends initialize. It authenticates. It opens a session with session/new, or resumes one with session/load. It sends the user’s text with session/prompt. Assistant text comes back as session/update notifications while the model streams. If a tool needs a decision, the agent sends session/request_permission and waits. The client can send session/cancel to stop the turn.
If the client never answers a permission request, the tool call sits there. ACP does not skip the approval the interactive CLI would have asked for.
ACP in each tool
Cursor and Grok Build document an ACP server command. Claude Code and Codex document other ways for a program to drive the agent. Those other ways are not described as ACP.
| Claude Code | Codex | Cursor | Grok Build | |
|---|---|---|---|---|
| ACP command | Not documented | Not documented | agent acp | grok agent stdio |
| Transport | Not documented | Not documented as ACP | stdio, newline-delimited JSON-RPC 2.0 | stdin and stdout, JSON-RPC |
| Auth the page names | Not documented | Not documented as ACP | cursor_login, or a key you passed at startup | A local login, or XAI_API_KEY |
| Where assistant text arrives | Not documented | Not documented as ACP | session/update | session/update chunks. session/prompt returns completion metadata |
Claude Code
Claude Code’s docs index does not list ACP. The programmatic interface it does document is headless mode: claude -p, or the Agent SDK. That is a prompt and a result. It is not a JSON-RPC session an editor attaches to.
See Claude Code headless mode.
OpenAI Codex
The Codex app-server page describes a JSON-RPC interface for rich clients, including the VS Code extension. Transports there include stdio. That page does not call the protocol ACP, and it does not list session/prompt or session/update. Treat app-server as its own interface. The page is Codex app-server.
Cursor
agent acp starts the CLI as an ACP server. Cursor’s page says to use plain agent for a normal terminal session. ACP is for a custom client or another editor.
The documented flow is initialize, then authenticate with methodId set to cursor_login, then session/new or session/load, then session/prompt. The sample initialize sends protocolVersion: 1. While the model streams, the client reads session/update. A permission request expects one of allow-once, allow-always, or reject-once.
You can log in first with agent login. You can also pass --api-key (or CURSOR_API_KEY) or --auth-token (or CURSOR_AUTH_TOKEN) on the same command line as acp. agent -e https://api2.cursor.sh acp sets the endpoint. agent -k acp is the documented TLS option on that page.
Modes match the CLI: agent for full tools, plan for read-only planning, ask for read-only questions. MCP servers come from a project or user .cursor/mcp.json. Team MCP servers from the Cursor dashboard are not supported in ACP.
Cursor also sends extension methods. cursor/ask_question and cursor/create_plan block until the client responds. cursor/update_todos, cursor/task, and cursor/generate_image are notifications.
Zed can spawn agent acp. JetBrains and Neovim (avante.nvim) are the other editor examples on the page. The Neovim block points command at ~/.local/bin/agent, passes acp as the only argument, and sets auth_method to cursor_login.
See Cursor’s ACP docs.
Grok Build
grok agent stdio runs Grok as an ACP agent. Use it when an editor or another tool should own the UI. A terminal session stays on grok.
The docs assume grok is already authenticated, or that XAI_API_KEY is set. Assistant text arrives as session/update chunks with sessionUpdate set to agent_message_chunk. session/prompt itself returns completion metadata.
Sessions are the same records the TUI and headless mode use, under ~/.grok/sessions/. In a script or in CI, pass --no-auto-update, or set auto_update = false under [cli] in ~/.grok/config.toml, so a background update check does not run.
How to use Grok Build walks through this command next to the JSON-RPC shape. How to use fx is a different agent that also speaks ACP, via fx acp.
See Grok Build headless and ACP.
Details checked against each vendor’s documentation in November 2026.
A real example
You want Neovim to drive Cursor’s agent, and you already ran agent login. The providers table from Cursor’s avante.nvim example is the piece that starts ACP:
acp_providers = {
cursor = {
command = os.getenv("HOME") .. "/.local/bin/agent",
args = { "acp" },
auth_method = "cursor_login",
},
},
The rest of that plugin spec, including provider = "cursor" and mode = "agentic", is on the ACP page. Adjust command if agent is not at ~/.local/bin/agent.
For Grok in a script, the documented launch is:
grok --no-auto-update agent stdio
CLI Tools Cabinet lists the agent binaries on the machine, which is the command an editor has to spawn. The CLI tools tutorial is the habit of reading that catalog before guessing a binary name.
When to use ACP
Use it when the editor is the UI and the coding agent should be a process it starts and stops. Cursor’s own examples are JetBrains, Neovim, and Zed. Grok’s page says the same thing in fewer words: IDE or tool integration, rather than a terminal session.
Use agent or grok when you are the client. Use headless mode when a script needs one answer and does not want to implement JSON-RPC.
Pitfalls
A client that prints the agent’s stdout to the user will also print protocol frames, unless it parses each line and only shows agent_message_chunk text. Cursor’s sample client does that split. Logs belong on stderr.
ACP does not import every MCP server the desktop app can see. Cursor’s page says dashboard team servers are out. Launch agent from the project directory so the project .cursor/mcp.json is the one it reads.
session/request_permission blocks the tool. Auto-approving allow-once in a client you do not watch is the same decision as approving that tool in the terminal. Read the request before the client answers it.
Claude Code and Codex can both be driven by a program. Wiring either one up as if it spoke Cursor’s ACP methods will fail, because those docs do not describe that server.
Related on flaviocopes.com
- How to use Grok Build shows
grok agent stdioand howsession/updatediffers fromsession/prompt. - How to use fx shows
fx acpas the editor entry point for a different agent that speaks the same protocol. - Headless mode is the one-prompt programmatic path, for scripts that should not speak ACP.
- CLI Tools Cabinet catalogs the installed agent CLIs an editor would put in
command.
Related glossary entries
- Headless mode: Headless mode runs a coding agent from a script, with no chat UI. How claude -p, codex exec, the Cursor CLI and grok -p differ on permissions.
- Plugins: A plugin bundles skills, hooks and tools you install together. How plugins and marketplaces work in Claude Code, Codex, Cursor and Grok Build.
- Sessions: A session is a saved coding-agent conversation you can resume later. How Claude Code, Codex, the Cursor CLI and Grok Build store, name, resume and fork one.
- Slash commands: Slash commands are the /name controls inside a coding agent session. How they work in Claude Code, Codex, Cursor and Grok Build, and how to add your own.
Want me to talk about your product? You can sponsor this site.