--- summary: "Run the ACP bridge for IDE integrations" read_when: - Setting up ACP-based IDE integrations - Debugging ACP session routing to the Gateway title: "acp" --- # acp Run the [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an Agdi Gateway. This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway over WebSocket. It keeps ACP sessions mapped to Gateway session keys. `agdi acp` is a Gateway-backed ACP bridge, not a full ACP-native editor runtime. It focuses on session routing, prompt delivery, and basic streaming updates. ## Compatibility Matrix | ACP area | Status | Notes | | --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `initialize`, `newSession`, `prompt`, `cancel` | Implemented | Core bridge flow over stdio to Gateway chat/send + abort. | | `listSessions`, slash commands | Implemented | Session list works against Gateway session state; commands are advertised via `available_commands_update`. | | `loadSession` | Partial | Rebinds the ACP session to a Gateway session key and replays stored user/assistant text history. Tool/system history is not reconstructed yet. | | Prompt content (`text`, embedded `resource`, images) | Partial | Text/resources are flattened into chat input; images become Gateway attachments. | | Session modes | Partial | `session/set_mode` is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope. | | Session info and usage updates | Partial | The bridge emits `session_info_update` and best-effort `usage_update` notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh. | | Tool streaming | Partial | `tool_call` / `tool_call_update` events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed. | | Per-session MCP servers (`mcpServers`) | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the Agdi gateway or agent instead. | | Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods. | | Client terminal methods (`terminal/*`) | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls. | | Session plans / thought streaming | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates. | ## Known Limitations - `loadSession` replays stored user and assistant text history, but it does not reconstruct historic tool calls, system notices, or richer ACP-native event types. - If multiple ACP clients share the same Gateway session key, event and cancel routing are best-effort rather than strictly isolated per client. Prefer the default isolated `acp:` sessions when you need clean editor-local turns. - Gateway stop states are translated into ACP stop reasons, but that mapping is less expressive than a fully ACP-native runtime. - Initial session controls currently surface a focused subset of Gateway knobs: thought level, tool verbosity, reasoning, usage detail, and elevated actions. Model selection and exec-host controls are not yet exposed as ACP config options. - `session_info_update` and `usage_update` are derived from Gateway session snapshots, not live ACP-native runtime accounting. Usage is approximate, carries no cost data, and is only emitted when the Gateway marks total token data as fresh. - Tool follow-along data is best-effort. The bridge can surface file paths that appear in known tool args/results, but it does not yet emit ACP terminals or structured file diffs. ## Usage ```bash agdi acp # Remote Gateway agdi acp --url wss://gateway-host:18789 --token # Remote Gateway (token from file) agdi acp --url wss://gateway-host:18789 --token-file ~/.agdi/gateway.token # Attach to an existing session key agdi acp --session agent:main:main # Attach by label (must already exist) agdi acp --session-label "support inbox" # Reset the session key before the first prompt agdi acp --session agent:main:main --reset-session ``` ## ACP client (debug) Use the built-in ACP client to sanity-check the bridge without an IDE. It spawns the ACP bridge and lets you type prompts interactively. ```bash agdi acp client # Point the spawned bridge at a remote Gateway agdi acp client --server-args --url wss://gateway-host:18789 --token-file ~/.agdi/gateway.token # Override the server command (default: agdi) agdi acp client --server "node" --server-args agdi.mjs acp --url ws://127.0.0.1:19001 ``` Permission model (client debug mode): - Auto-approval is allowlist-based and only applies to trusted core tool IDs. - `read` auto-approval is scoped to the current working directory (`--cwd` when set). - Unknown/non-core tool names, out-of-scope reads, and dangerous tools always require explicit prompt approval. - Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source). ## How to use this Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want it to drive an Agdi Gateway session. 1. Ensure the Gateway is running (local or remote). 2. Configure the Gateway target (config or flags). 3. Point your IDE to run `agdi acp` over stdio. Example config (persisted): ```bash agdi config set gateway.remote.url wss://gateway-host:18789 agdi config set gateway.remote.token ``` Example direct run (no config write): ```bash agdi acp --url wss://gateway-host:18789 --token # preferred for local process safety agdi acp --url wss://gateway-host:18789 --token-file ~/.agdi/gateway.token ``` ## Selecting agents ACP does not pick agents directly. It routes by the Gateway session key. Use agent-scoped session keys to target a specific agent: ```bash agdi acp --session agent:main:main agdi acp --session agent:design:main agdi acp --session agent:qa:bug-123 ``` Each ACP session maps to a single Gateway session key. One agent can have many sessions; ACP defaults to an isolated `acp:` session unless you override the key or label. Per-session `mcpServers` are not supported in bridge mode. If an ACP client sends them during `newSession` or `loadSession`, the bridge returns a clear error instead of silently ignoring them. ## Use from `acpx` (Codex, Claude, other ACP clients) If you want a coding agent such as Codex or Claude Code to talk to your Agdi bot over ACP, use `acpx` with its built-in `agdi` target. Typical flow: 1. Run the Gateway and make sure the ACP bridge can reach it. 2. Point `acpx agdi` at `agdi acp`. 3. Target the Agdi session key you want the coding agent to use. Examples: ```bash # One-shot request into your default Agdi ACP session acpx agdi exec "Summarize the active Agdi session state." # Persistent named session for follow-up turns acpx agdi sessions ensure --name codex-bridge acpx agdi -s codex-bridge --cwd /path/to/repo \ "Ask my Agdi work agent for recent context relevant to this repo." ``` If you want `acpx agdi` to target a specific Gateway and session key every time, override the `agdi` agent command in `~/.acpx/config.json`: ```json { "agents": { "agdi": { "command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 agdi acp --url ws://127.0.0.1:18789 --token-file ~/.agdi/gateway.token --session agent:main:main" } } } ``` For a repo-local Agdi checkout, use the direct CLI entrypoint instead of the dev runner so the ACP stream stays clean. For example: ```bash env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node agdi.mjs acp ... ``` This is the easiest way to let Codex, Claude Code, or another ACP-aware client pull contextual information from an Agdi agent without scraping a terminal. ## Zed editor setup Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed’s Settings UI): ```json { "agent_servers": { "Agdi ACP": { "type": "custom", "command": "agdi", "args": ["acp"], "env": {} } } } ``` To target a specific Gateway or agent: ```json { "agent_servers": { "Agdi ACP": { "type": "custom", "command": "agdi", "args": [ "acp", "--url", "wss://gateway-host:18789", "--token", "", "--session", "agent:design:main" ], "env": {} } } } ``` In Zed, open the Agent panel and select “Agdi ACP” to start a thread. ## Session mapping By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix. To reuse a known session, pass a session key or label: - `--session `: use a specific Gateway session key. - `--session-label