Skip to main content

Agent Client Protocol (ACP)

AiderDesk supports the Agent Client Protocol (ACP), a standardized protocol for communication between code editors/IDEs and AI coding agents. This means you can use AiderDesk as an AI agent inside any ACP-compatible editor or client — such as Zed, JetBrains AI Assistant, VS Code, neovim, and many others.

ACP is similar to the Language Server Protocol (LSP), but for AI coding agents. Instead of each editor building a custom integration for every agent, ACP provides a single standard. Any ACP-compatible editor can use any ACP-compatible agent.

How It Works​

AiderDesk's ACP server is a thin stdio bridge that connects an ACP client (your editor) to a running AiderDesk instance. When your editor launches the ACP agent, AiderDesk receives prompts over JSON-RPC, processes them through its existing task system (via the REST API), and streams back responses, tool calls, diffs, and reasoning in real time.

┌─────────┐     JSON-RPC (stdio)      ┌──────────────┐     HTTP/SSE      ┌─────────────────┐
│  Editor  │ ◄──────────────────────► │  aiderdesk   │ ◄───────────────► │  AiderDesk Server │
│ (ACP     │                          │  acp (CLI)   │                   │  (Electron /      │
│  Client) │                          │              │                   │   Docker / npm)   │
└─────────┘                          └──────────────┘                   └─────────────────┘

The aiderdesk acp command does not start a server — it connects to an already-running AiderDesk instance and bridges ACP protocol messages to its REST API.

Prerequisites​

A running AiderDesk instance is required

The ACP bridge connects to a running AiderDesk server. It does not start one. Make sure AiderDesk is running in one of the following ways:

1. Electron Desktop App​

If you have the desktop app installed and running, the ACP bridge will connect to it on the default port (24337).

2. Docker​

Run AiderDesk in headless mode via Docker. See the Docker guide for full setup instructions.

docker run -d \
  --name aiderdesk \
  -p 24337:24337 \
  -v ~/aiderdesk-data:/app/data \
  -v ~/.aider-desk:/root/.aider-desk \
  -v ~/projects:/projects \
  ghcr.io/hotovo/aider-desk:latest

3. npm CLI​

Install and run AiderDesk as a global npm package. See the npm CLI guide for details.

npm install -g @aiderdesk/aiderdesk
aiderdesk start

Verifying AiderDesk is Running​

Before configuring your editor, verify AiderDesk is reachable:

curl http://localhost:24337/api/health
# Expected: {"status":"ok"}

Installation​

The ACP bridge is included in the aiderdesk CLI, which is part of the @aiderdesk/aiderdesk npm package.

npm install -g @aiderdesk/aiderdesk

You can verify the ACP command is available:

aiderdesk acp --help

Usage​

aiderdesk acp [options]

Options​

OptionDescription
-p, --port <port>AiderDesk server port (default: 24337, env: AIDER_DESK_PORT)
--host <host>AiderDesk server host (default: localhost)

The command communicates over stdio using JSON-RPC with newline-delimited JSON (NDJSON), as defined by the ACP specification. You normally don't run this command directly — your editor launches it as a subprocess.

Port Configuration​

The port can be configured in three ways (highest priority first):

  1. CLI flag: aiderdesk acp --port 8080
  2. Environment variable: AIDER_DESK_PORT=8080 aiderdesk acp
  3. Default: 24337

Configuring ACP Clients​

To use AiderDesk as an ACP agent, register it in your editor's ACP/agent server configuration. The configuration tells the editor what command to run to start the agent.

Zed​

Add AiderDesk to your Zed agent_servers configuration (~/.config/zed/settings.json):

{
  "agent_servers": {
    "AiderDesk": {
      "command": "npx",
      "args": ["@aiderdesk/aiderdesk", "acp"]
    }
  }
}

If you installed AiderDesk globally, you can use the aiderdesk command directly:

{
  "agent_servers": {
    "AiderDesk": {
      "command": "aiderdesk",
      "args": ["acp"]
    }
  }
}

To connect to a non-default port, pass --port:

{
  "agent_servers": {
    "AiderDesk": {
      "command": "aiderdesk",
      "args": ["acp", "--port", "8080"]
    }
  }
}

JetBrains IDEs​

JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm, GoLand, etc.) support ACP via AI Assistant. Configure AiderDesk as a custom agent server in JetBrains settings under Settings → Tools → AI Assistant → Custom Agent Servers:

  • Name: AiderDesk
  • Command: aiderdesk acp (or npx @aiderdesk/aiderdesk acp)

Visual Studio Code​

Install an ACP extension such as ACP Client or ACP Pro, then configure AiderDesk as an agent server:

{
  "acp.servers": {
    "AiderDesk": {
      "command": "aiderdesk",
      "args": ["acp"]
    }
  }
}

neovim​

Using CodeCompanion:

require("codecompanion").setup({
  adapters = {
    aiderdesk = function()
      return require("codecompanion.definitions.adapter")
        :new({
          name = "aiderdesk",
          scheme = "acp",
          cmd = "aiderdesk",
          args = { "acp" },
          env = {},
        })
    end,
  },
})

Generic Configuration​

For any ACP-compatible client, the agent server definition follows this pattern:

FieldValue
NameAiderDesk
Commandaiderdesk (or npx @aiderdesk/aiderdesk)
Args["acp"]
Working directoryYour project directory
Port overrideAdd --port <port> to args
Host overrideAdd --host <host> to args

See the full list of ACP-compatible clients for more configuration options.

Session Configuration​

When you start a new ACP session, AiderDesk exposes several configurable options that the client may present as dropdowns or selectors. You can set these before or during a session.

Chat Mode​

Selects the chat mode for the session:

ModeDescription
AgentAgent mode with full tool access
CodeCode mode using Aider for edits
AskAsk questions without making changes
ArchitectDesign and plan without implementation
ContextAdd context files to the conversation

Custom modes defined per-project are also included if available.

Agent Profile​

Selects the agent profile to use. This option is only visible when the selected chat mode is Agent (i.e., not one of the Aider modes: Code, Ask, Architect, Context). The list is fetched from your configured agent profiles, or defaults to the project's default profile.

Autonomy​

Controls how much human oversight the agent has:

ModeDescription
ManualRequires approval for every tool call and plan
GuidedAuto-approves tool calls, waits for plan approval
AutonomousRuns without interruption

What You Get​

When using AiderDesk through ACP, your editor receives rich, structured updates:

  • Agent message streaming — Responses stream in real time as the agent works
  • Agent reasoning — Thinking/reasoning steps are displayed as they occur
  • Tool calls — File reads, edits, searches, bash commands, and more are shown with their inputs and outputs
  • Diffs — File edits and writes are rendered as diffs that the editor can display natively
  • Terminal output — Bash command results are surfaced as terminal content
  • Usage and cost — Token usage and cost information is reported after each response
  • Session info — Task names and metadata are synced with the editor
  • Cancellation — You can cancel in-progress prompts; the editor will notify AiderDesk to interrupt the task

Troubleshooting​

"AiderDesk server is not running" error​

The ACP bridge connects to a running AiderDesk server. Make sure it's started:

  • Desktop app: Launch the AiderDesk application
  • Docker: docker start aiderdesk (or docker run ... — see Docker guide)
  • npm CLI: Run aiderdesk start (see npm CLI guide)

Verify the server is healthy:

curl http://localhost:24337/api/health

Wrong port​

If AiderDesk is running on a non-default port, pass --port to the ACP command:

{
  "command": "aiderdesk",
  "args": ["acp", "--port", "8080"]
}

Or set the AIDER_DESK_PORT environment variable in the agent server config:

{
  "command": "aiderdesk",
  "args": ["acp"],
  "env": { "AIDER_DESK_PORT": "8080" }
}

Remote AiderDesk instance​

If your AiderDesk server is running on a different host, use the --host flag:

{
  "command": "aiderdesk",
  "args": ["acp", "--host", "192.168.1.100"]
}

Sessions not persisting​

ACP sessions map to AiderDesk tasks. Each new ACP session creates a new task. To resume a conversation, use your editor's session management features — AiderDesk will reuse the existing task if the session continues.

Learn More​