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": {
      "type": "custom",
      "command": "crabcode",
      "args": ["acp"],
      "env": {}
    }
  }
}

Provider login

Connect a provider in an interactive terminal without starting chat:

crabcode acp --login

Choose a provider ID, then use the existing OpenAI/xAI OAuth flow or enter an API key (hidden). Local providers do not need credentials. Existing credentials can be kept or replaced. The command exits after setup; restart or reconnect your ACP client afterward. The normal TUI /connect flow remains available.

Clients advertising clientCapabilities.auth.terminal discover terminal login automatically. Modern terminal-auth arguments append --login to the configured crabcode acp invocation. Older registry clients opting in through _meta["terminal-auth"] receive replacement arguments acp --login. Terminal-tool hosting alone does not imply login support. Clients without terminal-auth support should use manual setup.

Credentials remain in Crabcode's normal state directory; the editor does not receive API keys or OAuth tokens. Login is interactive and rejects piped input; normal ACP stdout remains JSON-RPC-only.

Registry distribution

Registry submission is separate from ACP support and is not automatic. Native releases use .tar.gz on macOS/Linux and .zip on Windows, with checksums. The npm installer also supports older .tar.xz releases and writes installation diagnostics to stderr.

Before submitting an entry to the ACP Registry, publish a release, verify its actual archives and executable paths, run the registry's clean-home authentication check, and smoke-test a client such as Codync. A provider-free local handshake check is available with python3 scripts/verify-acp-registry.py /path/to/crabcode. This checks discovery only, not real OAuth or API-key validity.

The entry requires crabcode/agent.json and a monochrome 16×16 crabcode/icon.svg. No registry entry is submitted by the release workflow.

Capability Matrix

All Crabcode-side capabilities in this matrix are implemented. Conditions in the last column are editor, model, provider, or protocol requirements rather than incomplete server behavior.

AreaFull behaviorStatusRuntime or protocol requirements
TransportJSON-RPC over stdio through crabcode acp, protocol-only stdout, clean stdin EOF shutdown, request failures returned as JSON-RPC errors without closing the connection, and subprocess coverage for initialize, session loading failures, session creation, command advertisement, and command dispatch.FullThe subprocess wrapper must not write banners or logs to stdout.
SessionsCreate, cursor-list, load, resume, close, delete, and fork all persisted sessions, including child sessions. Lists include Crabcode parent/root IDs in ACP _meta; forks preserve the source title, regenerate message IDs, copy attachments independently, and publish commands for the new session. Delete removes persisted history and managed attachments.FullACP has no standard nested-session tree field, so hierarchy is exposed through the crabcode metadata extension while the standard list remains flat.
PromptsText, embedded resources, PNG/JPEG/GIF/WebP images, and WAV/MP3 audio; assistant text and reasoning stream back to the editor. Attachments use private per-session storage, survive load/resume, copy independently on fork, delete with persisted sessions, and readable legacy paths migrate automatically on load.FullThe selected model route must advertise the matching input modality. Audio uses verified OpenAI-compatible Chat Completions input_audio; unsupported provider transports return a clear error instead of dropping media.
Modes and modelsVisible primary agents, selectable model catalog entries, and supported reasoning-effort values are session-local ACP configuration options.FullAvailable reasoning values follow the selected model's catalog capability.
ToolsPending and completed/failed tool calls include ACP kinds, titles, raw input/output, full text plus bounded previews, normalized locations, native editor images/audio/resources, annotations, metadata, and full-file diffs. The model receives the structured textual/raw representation and supported image results. Unknown future MCP blocks are preserved in raw output and rendered as readable JSON text instead of being dropped. OpenAI and OpenAI-compatible requests recursively sanitize unsupported regex lookaround constraints from model-facing MCP tool schemas while preserving server-side validation.FullA future content type can only be native when ACP defines a matching content block; the lossless text/raw fallback remains available otherwise.
PermissionsPermission requests carry the originating tool-call ID, raw input, normalized locations, and preflight full-file diffs for edit, write, write_files, and multi-file apply_patch, with allow once, always allow for this session, and reject choices. Session grants are shared across turns and cover later accesses within the approved folder scope. Patch previews use the same hunk matching without mutating disk.FullPreviews never read protected external or sensitive files before approval. Those requests show proposed/raw input and locations without existing contents. Mixed protected patches omit their whole preflight diff. Invalid patches also retain raw input and remain blocked until the user decides.
Cancellationsession/cancel interrupts model turns, questions, compaction, and terminal creation/execution while keeping the session reusable. Crabcode maps completion, output limit, configured turn limit, refusal/content filtering, and cancellation to ACP end_turn, max_tokens, max_turn_requests, refusal, and cancelled.FullProvider failures that are not normal stop conditions remain JSON-RPC/tool errors, as required by ACP's stop-reason model.
Commands and skillsSession updates publish global/workspace skills, project custom commands, and /skills, /mcp, /compact, and /btw. Commands are dispatched from regular ACP text prompts as required by the protocol. Custom command agent/model overrides apply to that turn while embedded resources and media remain attached. /skills and /mcp return local results without spending or persisting a model turn; /mcp reports live connection/auth/failure status. /compact rewrites persisted context, while OpenCode-compatible compaction.auto, compaction.prune, and compaction.reserved also apply to normal ACP turns. /btw runs a no-tools side question without changing the main transcript. Unknown slash commands return an explicit error.FullEditor-native session/model/mode operations replace TUI-only navigation dialogs and pickers rather than duplicating their terminal UI commands.
MCPProject MCP and client-supplied stdio, HTTP, and SSE servers merge into the session. Static headers, structured results, live status, resources, annotations, images, audio, and metadata are preserved. Project-configured remote MCP continues to use Crabcode's OAuth credential flow.FullACP currently advertises only the HTTP/SSE transport flags; its client-server schema has no stdio flag or remote OAuth fields. Client-supplied remote auth can still be provided through headers.
Terminalsterminal_session and terminal-mode bash use the editor terminal host through create, embed, wait, output, kill, and release. Output is bounded for the model, and cancellation also covers terminal creation.FullThe editor must advertise terminal hosting. User input and resize happen directly in the embedded editor terminal because ACP has no agent-issued stdin/resize requests.
QuestionsAgent questions use capability-gated ACP form elicitation with validated non-empty prompts/options, unique labels, ordered single/multi-select answers, custom text, cardinality checks, deduplication, length bounds, cancellation, and safe skip behavior.FullForm elicitation is an unstable ACP capability and is only sent to editors that advertise it.
UsageProvider input/output/cache-read/cache-write usage is aggregated across multi-step turns and persisted. ACP receives live context occupancy updates while text, reasoning, tool calls, and tool results stream, plus provider-reported prompt/cache floors after each model step and cumulative USD cost. Detailed token/cache values and whether the context size is known are included in crabcode _meta. Context-window size resolves from the effective selectable model catalog first, then discovery or custom-provider metadata. Catalog pricing is cache-aware.FullProviders that omit usage or models without pricing cannot supply authoritative token or cost data; Crabcode still emits live estimated context growth and marks unknown context size in metadata.

Runtime requirements

  • Image and audio prompts require a selected model route with the corresponding input modality.
  • ACP terminal embedding and question forms require the editor to advertise those client capabilities during initialization.
  • Client-supplied remote MCP OAuth parameters are not part of the current ACP server descriptor. Use static headers from the editor, or configure the MCP server in Crabcode to use Crabcode's OAuth flow.
  • Fields under _meta.crabcode are backwards-compatible Crabcode extensions for session hierarchy and detailed usage accounting.

Session behavior

session/close detaches the editor and cancels any active turn. It does not delete Crabcode session history. session/delete removes persisted history and managed attachments. List cursors page through the complete non-archived result set. Load replays the stored transcript; resume restores the session configuration without replaying prior content. Fork creates a new persisted session with a copied transcript and independently managed attachments. Child sessions are listed as normal entries with hierarchy metadata under _meta.crabcode. Invalid or failed session operations return a normal JSON-RPC error response and leave the ACP stdio connection available for later requests.

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 with Allow once, Always allow for this session, and Reject choices. Choosing the session-wide option remembers the normalized permission scope for that attached ACP session, including later tool calls and later prompt turns. For external-folder access, approving a folder also covers files and nested directories beneath it. The grant is intentionally not written to project configuration or global preferences: closing/detaching the ACP session or restarting the server clears it, and loading/resuming the persisted transcript starts with a fresh permission state. Forked sessions also start with fresh grants. If the editor cannot respond or disconnects, Crabcode denies the request rather than continuing unattended.

Question forms are only sent to editors that advertise ACP form elicitation support. Declining, cancelling, disconnecting, or using an editor without that capability returns empty answers to the agent so the session can continue without waiting indefinitely.

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 and audio attachments are decoded under a 20 MiB-per-file limit and written to private session-managed storage under Crabcode's state directory (…/crabcode/attachments/<session-id>/). Audio input accepts WAV and MP3 only. Closing an editor session keeps those files because history remains loadable; deleting the persisted session removes its managed attachment directory. Forks receive independent copies so deleting either session does not break the other. Readable external or temporary attachment paths from older sessions are copied into managed storage the next time Crabcode loads the session.

The capability matrix matches what the ACP server implements today. Crabcode only advertises protocol capability flags it handles (loadSession, image, audio, and embedded-context prompts, HTTP/SSE MCP, and list/resume/fork/close/delete session ops). Client-side form elicitation and terminal hosting are capability-gated during initialization before Crabcode sends those requests. Stdio MCP is accepted even though the current ACP capability object has no separate stdio flag.