ACP (Agent Client Protocol)

Nanocoder can run as an Agent Client Protocol (ACP) server, letting ACP-compatible clients drive it as a native coding agent. Instead of the Ink terminal UI, Nanocoder speaks JSON-RPC over stdin/stdout, and the client renders the conversation, tool calls, diffs, and permission prompts in its own UI.

nanocoder --acp

You normally don't run this command yourself — the editor or extension spawns it for you (see Setup in Zed and the VS Code extension).

ACP vs. the VS Code companion

ACP is the transport for both the VS Code sidebar chat and other ACP clients (Zed, etc.). The older --vscode WebSocket path is a separate, opt-in legacy terminal companion for Ink TUI sessions — not how the sidebar works.

	Transport	Flag	Clients
ACP	JSON-RPC over stdin/stdout	--acp	VS Code sidebar, Zed, and other ACP clients
Legacy companion	WebSocket	--vscode	VS Code (opt-in terminal companion)

With ACP the client is the UI: the agent runs headless and everything (streaming text, tool cards, diffs, approvals) is rendered by the editor or sidebar. The legacy --vscode companion keeps the Nanocoder terminal TUI in charge and adds diff previews and editor context on top — see Legacy Companion Mode.

What works over ACP

• Streaming responses including reasoning/thinking, rendered in the editor's agent panel.
• Tool calls with rich cards — file tools report their kind and the files they touch, and edits (string_replace, write_file) include a before/after diff the editor can preview.
• Permission prompts — tools that need approval surface as the editor's own allow/deny prompt, respecting the current development mode.
• Development modes — normal, auto-accept, yolo, and plan are exposed as ACP session modes and selectable from the editor (sessions start in auto-accept).
• Model display and switching — the editor shows the current model and lets you switch between the models configured for your active provider.
• ask_user — when the agent asks a clarifying question, the options appear as selectable buttons in the editor. (Selection only; a free-form typed answer is not available over ACP.)
• @-mentioned files — files you reference in the editor are read and included in the prompt, using the editor's live buffer (including unsaved edits) when available.
• Session reload — reopening a thread is supported, so the editor won't error when restoring a session.

Setup in Zed

Zed is the reference ACP client. Register Nanocoder as a custom agent in Zed's settings.json (Cmd+,, or zed: open settings from the command palette):

{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp"]
    }
  }
}

Then:

1. Open a project folder in Zed (one that has a Nanocoder provider configured — see Requirements).
2. Open the Agent Panel and use the New Thread dropdown.
3. Choose Nanocoder and start prompting.

To pin a specific provider or model for the editor session, add them to args:

{
  "agent_servers": {
    "Nanocoder": {
      "command": "nanocoder",
      "args": ["--acp", "--provider", "ollama", "--model", "qwen2.5-coder:7b"]
    }
  }
}

Otherwise Nanocoder uses your configured default provider and last-used model. You can switch models later from Zed's model selector.

Requirements

• Nanocoder installed and on your PATH (a global install puts nanocoder on PATH).
• A configured provider. The ACP server resolves provider and model the same way the CLI does — from the project's agents.config.json (or your global config). See Providers.
• The editor spawns the agent in your project directory, so project-level config and relative paths resolve against the open folder.

Limitations

• Session history is in-memory. Reopening a thread within the same running agent restores its history, but after the editor (and agent process) fully restarts, a reloaded thread starts empty — it is usable, but prior messages are not replayed.
• ask_user is selection-only. ACP permission options have no text input, so the model receives whichever option you pick rather than a typed answer.
• Images and audio are not processed. Non-text attachments are noted to the model but not interpreted.

Troubleshooting

Nanocoder doesn't appear / the thread fails to start

• Confirm nanocoder --acp runs from your shell. If the editor was launched from the desktop (not a terminal), it may not see your shell's PATH — use an absolute path to the binary, or to the Node runtime, in the command/args.
• Check the editor's agent/log output for the spawn error.

"No provider configured" or it exits immediately

• The open folder has no resolvable provider/model. Add an agents.config.json to the project (or your global config), or pass --provider/--model in args. See Configuration.

Tagged files aren't seen by the model

• Make sure you reference the file through the editor's own file-mention UI so it sends the file as a resource. Plain text that merely names a path is not read automatically.