ACP

Editors run zidane through the Agent Client Protocol (ACP) v1. They start zidane-acp and talk to it over stdio. Your own process can embed the same server from zidane/acp.

Install#

npm install -g zidane
zidane-acp --help

From a checkout: bun install, then bun run acp --help. stdout carries only JSON-RPC frames. Logs go to stderr.

Connect from Zed#

Add a custom agent to Zed's settings.json:

{
  "agent_servers": {
    "Zidane": {
      "type": "custom",
      "command": "zidane-acp"
    }
  }
}

If Zed cannot find zidane-acp on PATH, use an absolute path. With no provider or model flags, zidane-acp:

• offers a model for every provider with stored credentials
• exposes Build and Plan modes
• saves sessions as JSON files in acp-sessions/ in zidane's data folder (files and folders), so Zed reopens threads after a restart
• gives sessions file read and write, edit, shell, directory listing, sub-agents, web_search and fetch_url

For a local or OpenAI-compatible provider:

{
  "agent_servers": {
    "Zidane Local": {
      "type": "custom",
      "command": "zidane-acp",
      "args": ["--provider", "local", "--base-url", "http://localhost:8000/v1", "--model", "my-model"],
      "env": { "LOCAL_LLM_API_KEY": "no-key" }
    }
  }
}

Credentials#

ACP has no way for an editor to pass provider keys. zidane-acp looks in this order:

1. Environment variables (<PROVIDER>_API_KEY, or the client's env block).
2. zidane's credentials file, written when you sign in from the terminal app. OAuth tokens refresh from it. A variable already set wins.
3. The legacy OAuth store, ~/.credentials.json.

Sign in once with the terminal app to keep keys out of settings.json. --no-credential-store uses environment variables only. ZIDANE_CREDENTIALS_PATH moves the credentials file (files and folders).

Models and modes#

Pick the models#

The first entry is the default (or --model, if listed). Switch models between turns. zidane refuses a switch during a prompt.

Modes#

Both modes send the same tool list, so a switch keeps the prompt cache. A gate refuses the calls Plan does not allow, and the next prompt carries a note that tells the model about the mode.

Model options#

zidane turns the model catalog into ACP session config options, applied from the next prompt. Reasoning models get a Thinking selector with the effort levels. Model flags such as Anthropic's fast mode get On/Off toggles.

What zidane-acp supports#

Files and terminals in the editor#

When the editor offers these at initialize, zidane runs the tool through the editor's buffers and terminals:

Through an editor terminal, shell cannot run in the background. The agent gets an error and reruns the command in the foreground.

Permissions#

shell, write_file, edit, multi_edit and mutating client tools ask through ACP's session/request_permission:

The preset is basic, plus web_search and fetch_url. zidane-acp advertises no slash commands.

Other ACP clients#

Any ACP v1 client can launch zidane-acp [options]. It takes the zidane run flags plus three of its own. The prompt and output flags (--prompt, --json, --stream-json, --format, --json-schema) do nothing.

--cwd applies when the client sends no session folder. Ctrl+C closes the sessions and exits 130; SIGTERM exits 143.

Vim and Neovim#

editors/vim is a Vim 9 and Neovim 0.9+ plugin on zidane-acp. It opens a panel over any window. Its tools let the agent inspect your setup, read :help and run commands you approve.

Plug 'Tahul/zidane', { 'rtp': 'editors/vim' }

Leaderz or :Zidane [prompt] opens it and sends your visual selection as context. See :help zidane.

Embed the server#

import { runAcpStdioServer } from 'zidane/acp'
import { anthropic } from 'zidane/providers'

const handle = runAcpStdioServer({
  provider: anthropic(),
  permission: { enabled: true },
})

process.once('SIGTERM', () => {
  void handle.close().finally(() => process.exit(143))
})

ACP sessions use a 1-hour prompt cache (behavior.cacheTtl: '1h'), because editor sessions go at a human pace. Set behavior.cacheTtl on the server options, agentOptions or the preset to change it.

Each session's system prompt is frozen on its first prompt and sent unchanged afterwards. Changes to skills, searchable tools or MCP instructions reach the model as notes. When the base prompt changed (for example a restart with a new system), the next prompt records the new one, and the provider reads the whole conversation again once.

zidane/acp also exports createAcpServer, JSON-RPC and content-mapping helpers, and ACP types for a custom transport.

Troubleshooting#

1. Run zidane-acp --help to confirm the binary starts.
2. Make sure that the editor uses the same command path and environment.
3. In Zed, open the ACP logs from the Command Palette.
4. Print nothing to stdout from a wrapper script. Clients expect only protocol frames.
5. Set ZIDANE_DEBUG=1 to log prompt-cache breaks and prompt re-captures to stderr.

Reference#

• zidane/acp