Skip to main content

Editor Integration Guide

Complete guide to ACP (Agent Client Protocol) and Ada editor integrations.

Overview

Ada provides Agent Client Protocol (ACP) integration for editors that can spawn a local agent process and communicate over JSON-RPC on stdin/stdout.

The user-facing command is:

bash
ada acp start

This is an Ada Rust CLI feature. The retired TypeScript ACP package was for the old TypeScript Ada CLI path and is no longer the implementation boundary.

Understanding ACP

ACP is:

  • JSON-RPC over stdio between an editor client and an Ada subprocess.
  • Editor-agnostic for clients that support ACP or can spawn subprocesses.
  • Session-oriented so prompt turns, updates, and cancellation share context.
  • Backed by Rust Ada/Lattice runtime for workspace resolution, provider access, assistant sessions, and persisted session metadata.

ACP is not a hosted remote-client API in Lovelace today. Streamable HTTP exists in the broader ACP spec as a draft direction, but Lovelace's supported ACP contract is local stdio.

Start ACP

Editors should launch Ada as the ACP subprocess:

bash
ada acp start

Use a workspace override when the editor cannot provide the desired working directory context:

bash
ada acp start --workspace-id default

Temporary provider overrides use the same runtime settings as the Ada Rust CLI:

bash
ada acp start --provider anthropic --model claude-sonnet-4-20250514

Check the local binary's ACP support surface:

bash
ada acp status
ada acp status --format json

Editor Configuration

Zed

Configure Zed to spawn Ada as an ACP agent server:

json
{
  "agent_servers": {
    "Ada": {
      "command": "ada",
      "args": ["acp", "start"],
      "env": {}
    }
  }
}

Custom Editors

Editors can launch Ada directly and exchange newline-delimited JSON-RPC:

python
import json
import subprocess

process = subprocess.Popen(
    ["ada", "acp", "start"],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
)

initialize = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
        "protocolVersion": 1,
        "clientCapabilities": {},
        "clientInfo": {"name": "custom-editor", "version": "0.1.0"},
    },
}

process.stdin.write(json.dumps(initialize) + "\n")
process.stdin.flush()
print(process.stdout.readline())

Protocol Flow

The supported flow is the ACP v1 lifecycle:

  1. Editor launches ada acp start.
  2. Editor sends initialize.
  3. Editor creates or loads a session with session/new or session/load.
  4. Ada returns initial session configuration options, including the live mode selector when supported by the installed binary.
  5. Editor sends user turns with session/prompt.
  6. Ada streams session/update notifications for messages, tool calls, and progress.
  7. Editor can cancel active work with session/cancel.

Security Model

Ada ACP is capability-based and local-first:

  • The editor process provides context; it does not get ambient authority.
  • Workspace resolution flows through the Rust runtime/session host.
  • Provider access and persisted assistant sessions stay behind Ada's runtime boundaries.
  • ACP protocol frames use stdout; logs and diagnostics use stderr or file logs so clients can parse stdout safely.

Troubleshooting

Editor Cannot Start ACP

Run:

bash
ada acp status
ada --version

Make sure the editor can find ada on PATH, or configure the full path to the installed Ada binary.

Protocol Output Is Invalid

ACP clients require stdout to contain only JSON-RPC frames. Do not wrap ada acp start with shell scripts that print banners or diagnostics to stdout.

Workspace Is Wrong

Pass an explicit workspace override:

bash
ada acp start --workspace-id <workspace-id>

Related