crabcode

ACP Integration

Run Crabcode as an Agent Client Protocol server for compatible editors.

Run Crabcode from an ACP-compatible editor or IDE with a stdio subprocess. ACP keeps the workspace, credentials, tools, permissions, and session history on the machine running Crabcode.

Start the server

crabcode acp

Use --cwd when the editor should start Crabcode for a specific workspace:

crabcode acp --cwd /absolute/path/to/project

ACP uses stdin and stdout for JSON-RPC traffic. Do not wrap the command with a program that writes banners or logs to stdout.

Editor configuration

For Zed, add an agent server to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "Crabcode": {
      "command": "crabcode",
      "args": ["acp"]
    }
  }
}

Configure a provider in the Crabcode TUI with /connect before starting an ACP session. Credentials remain in Crabcode's normal state directory; the editor does not receive API keys or OAuth tokens.

Capability Matrix

AreaSupported behaviorCurrent limitationsPlanned follow-up
TransportJSON-RPC over stdio through crabcode acp; clean stdin EOF shutdown.stdout must remain protocol-only.Add protocol-level subprocess integration coverage.
SessionsCreate, list, load, resume, close, and fork persisted root sessions.Replay message IDs are deterministic per load, not durable message IDs.Persist stable message IDs across streaming snapshots and reloads.
PromptsText, embedded text resources, and PNG, JPEG, GIF, or WebP image attachments; assistant text and reasoning stream back to the editor.Images require an image-capable selected model; audio prompt blocks are unsupported.Store ACP attachments persistently and add audio input support.
Modes and modelsVisible primary Crabcode agents, selectable /models catalog entries, and model-supported reasoning-effort selectors are available as ACP options; changes are session-local.Reasoning options depend on the selected model catalog metadata.Add richer provider-specific reasoning configuration.
ToolsTool calls and completed or failed results stream with ACP tool kinds, titles, raw input, and preview output.No normalized locations, diffs, full outputs, or result images yet.Preserve structured tool results, locations, patches, and image content in runtime events.
PermissionsExisting Crabcode permission prompts are forwarded with allow once, always allow, and reject choices.Permission requests use a generated ACP call ID because the current internal prompt lacks the originating tool-call ID.Carry the real tool-call ID and edit patch metadata through permission preflight.
Cancellationsession/cancel cancels the active turn and keeps the session reusable.Provider stop reasons are currently reduced to normal completion, cancellation, or a safe failure.Preserve output-limit and refusal stop reasons from the model runtime.
Commands and skillsSession updates publish available commands: project custom slash commands, workspace skills, plus built-in /skills and /mcp. Leading /… prompts expand through the same command and skill templates before the model turn.Built-in TUI commands such as /compact are not ACP-available commands; unknown /… lines pass through as plain text.Add more built-in commands (for example /compact) and richer command input schemas.
MCPProject MCP from Crabcode config runs as usual. Editors may also pass MCP servers on session/new; those servers are merged into the session config (stdio, HTTP, and SSE).HTTP and SSE client MCP are advertised; stdio client MCP is accepted and merged even though it is not a separate advertised capability flag.Surface richer MCP connection status and OAuth for remote client servers.
Terminals—ACP terminal embedding is not implemented.Add a client-terminal adapter for long-running shell sessions.
Questions—Interactive question prompts from the agent are not forwarded over ACP; the runtime skips them rather than blocking the editor.Map Crabcode questions to ACP permission-style or dedicated question requests.
UsageEstimated context-window usage is emitted when the selected model exposes a context limit.Provider-authoritative token and cost accounting is not complete; usage is omitted when no context limit is known.Retain provider input, output, cache, context, and cost data for authoritative usage updates.

Session behavior

session/close detaches the editor and cancels any active turn. It does not delete Crabcode session history. Load replays the stored transcript; resume restores the session configuration without replaying prior content. Fork creates a new persisted session with a copied transcript.

Safety notes

Crabcode applies the same configured permission rules in ACP as it does in the TUI. When a tool needs approval, the editor receives an ACP permission request. If the editor cannot respond or disconnects, Crabcode denies the request rather than continuing unattended.

Client-supplied MCP servers run with the same trust as project-configured MCP: stdio servers can execute local processes, and remote servers can send the headers and credentials the editor provides. Only attach MCP servers you trust for that workspace.

Image attachments are decoded under a size limit and written to temporary files under the system temp directory (…/crabcode/acp-images/) for the model turn. Prefer cleaning those files after long ACP sessions until automatic cleanup lands.

The capability matrix matches what the ACP server implements today. Crabcode only advertises protocol capability flags it handles (loadSession, image and embedded-context prompts, HTTP/SSE MCP, and list/resume/fork/close session ops).