{"id":51277470,"url":"https://github.com/maksugr/acp-devtools","last_synced_at":"2026-06-29T22:02:04.465Z","repository":{"id":362336790,"uuid":"1243796836","full_name":"maksugr/acp-devtools","owner":"maksugr","description":"See exactly what your editor and your coding agent say to each other — a transparent ACP proxy with a live web inspector, CLI, and read-only MCP server.","archived":false,"fork":false,"pushed_at":"2026-06-03T18:40:12.000Z","size":5075,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T20:09:26.746Z","etag":null,"topics":["acp","agent-client-protocol","ai-agents","coding-agent","debugger","developer-tools","devtools","jetbrains","mcp","zed"],"latest_commit_sha":null,"homepage":"http://playground.acp-devtools.dev/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maksugr.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-19T17:11:52.000Z","updated_at":"2026-06-03T18:53:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/maksugr/acp-devtools","commit_stats":null,"previous_names":["maksugr/acp-devtools"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/maksugr/acp-devtools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksugr%2Facp-devtools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksugr%2Facp-devtools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksugr%2Facp-devtools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksugr%2Facp-devtools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maksugr","download_url":"https://codeload.github.com/maksugr/acp-devtools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maksugr%2Facp-devtools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34944147,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-29T02:00:05.398Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acp","agent-client-protocol","ai-agents","coding-agent","debugger","developer-tools","devtools","jetbrains","mcp","zed"],"created_at":"2026-06-29T22:02:01.314Z","updated_at":"2026-06-29T22:02:04.459Z","avatar_url":"https://github.com/maksugr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/logo-dark.png\"\u003e\n    \u003cimg alt=\"ACP Devtools\" src=\"assets/logo.png\" width=\"420\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/acp-devtools\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/acp-devtools\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/acp-devtools\"\u003e\u003cimg alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/acp-devtools\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/maksugr/acp-devtools/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"CI\" src=\"https://github.com/maksugr/acp-devtools/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/license-MIT-blue.svg\"\u003e\u003c/a\u003e\n  \u003ca href=\"package.json\"\u003e\u003cimg alt=\"Node\" src=\"https://img.shields.io/badge/node-%E2%89%A522-brightgreen\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/architecture-v2-dark.svg\"\u003e\n    \u003cimg alt=\"Architecture: editor and agent exchange ACP frames through the acp-devtools proxy, which feeds three consumer interfaces — CLI, UI, and MCP.\" src=\"assets/architecture-v2.svg\" width=\"820\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003eSee exactly what your editor and your coding agent say to each other.\u003c/strong\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003eACP Devtools captures every JSON-RPC frame between them, stores each session in SQLite, and streams it to a live web inspector — replay, diff, spec-validation, plus a CLI and a read-only MCP server.\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://playground.acp-devtools.dev/?url=https://gist.githubusercontent.com/maksugr/0059be3aba62538c099ae96f0bf34bbb/raw/06a5d8c926d6ad99a410688a07f8e35bd89bac36/gistfile1.txt\"\u003e\u003cstrong\u003eTry it in your browser →\u003c/strong\u003e\u003c/a\u003e\u0026nbsp; opens the playground pre-loaded with a sample session. See the timeline, inspect frames, open the perf panel. Drop your own \u003ccode\u003esession.json\u003c/code\u003e to inspect your traffic. \u003ca href=\"#playground\"\u003eMore about the playground ↓\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"A 16-second tour: pick a session, click a frame to see its payload, cycle the Tree/Raw/Meta/Spec tabs, open the session-info drawer, open the performance dashboard with its waterfall, diff two sessions, switch theme.\" src=\"assets/demo.webp\" width=\"640\"\u003e\n\u003c/p\u003e\n\n## What is ACP?\n\nThe [Agent Client Protocol](https://agentclientprotocol.com/get-started/introduction)\nis an open, newline-delimited JSON-RPC wire format that lets an editor (Zed,\nWebStorm, IntelliJ, Neovim, Visual Studio via ReSharper) drive a coding agent\n(Claude Code, Codex, Goose, OpenCode, and\n[40+ others](https://agentclientprotocol.com/get-started/agents)) over stdio,\nwithout either side knowing the other's implementation. **ACP Devtools sits in the middle of that stdio pipe — neither side knows it's there.**\n\nNever seen the wire before? [Anatomy of an ACP session](docs/session-anatomy.md)\nwalks one real capture frame by frame — handshake, prompt turn, a tool call\nbehind a permission dialog, a cancelled turn — and it's the same session the\n[playground](#playground) loads, so you can click along.\n\n## Who it's for\n\n- **Agent authors** — see exactly what an editor sends, and validate your wire\n  output against the spec.\n- **Editor / plugin developers** — see what the _other_ side sends (WebStorm and\n  Zed disagree on capabilities, `_meta`, and id format) and test against\n  recorded traffic without burning tokens.\n- **Anyone debugging a chat** — find why `session/prompt` took 60s, or replay\n  yesterday's broken session and step to the failing tool call.\n- **CI** — gate releases on spec conformance and latency regressions, headless\n  (exit-code-driven [recipe](docs/recipes.md#gate-a-build-in-ci)).\n\n## Features\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTransparent proxy\u003c/b\u003e — captures every frame in both directions\u003c/summary\u003e\n\nSits between editor and agent over stdio (newline-delimited JSON-RPC 2.0).\nNeither side knows it's there.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTimeline + JSON detail\u003c/b\u003e — vertical scroll of every frame, click for the payload\u003c/summary\u003e\n\nEach row shows direction, kind, method, rpc id, size, and latency to its paired\nrequest. The detail panel renders the full payload as a spec-aware tree —\nhover any field for its schema description, `⚠ ext` badges mark `_meta` and\nfields not declared in the spec.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eStream clusters\u003c/b\u003e — \u003ccode\u003eagent_message_chunk\u003c/code\u003e runs collapse to one \u003ccode\u003eSTR\u003c/code\u003e row\u003c/summary\u003e\n\nA shimmer bar marks the cluster while chunks are still arriving — tells\n\"agent thinking\" apart from \"agent stuck\". Click to expand the individual\nchunks.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSpec validation\u003c/b\u003e — every frame against the official ACP JSON schema\u003c/summary\u003e\n\nInvalid frames get a red `⚠ SPEC N` badge in the timeline, per-error ajv\ndetails in the detail panel, and a footer aggregate across the session. CLI:\n`acp-devtools validate \u003cid\u003e` exits 1 on violations — wire into CI. Frames that are valid today but omit a field the spec says will become mandatory get a softer amber `⚠ ADV N` advisory instead.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePerformance dashboard\u003c/b\u003e — per-method p50/p99/max + waterfall + insights\u003c/summary\u003e\n\nSortable table with latency sparklines, auto-detected insights (hotspot,\nlong-tail, outlier, busiest, errors), and a waterfall canvas with\ngap-compression for multi-hour sessions. CLI mirror: `stats \u003cid\u003e --by-method`\n— same percentile algorithm, same numbers to the millisecond.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMulti-session diff\u003c/b\u003e — frame-level + metadata + per-method p99 deltas\u003c/summary\u003e\n\nLCS-aligned frame view with click-to-expand field-level changes, plus a\nmetadata diff layer (versions, capabilities) and a per-method p99-delta layer.\nCLI: `diff \u003ca\u003e \u003cb\u003e` (add `--json` for machine output).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eSession metadata\u003c/b\u003e — versions, capabilities, mode/model, slash commands\u003c/summary\u003e\n\nDerived from the captured frames — client/agent versions, capability matrix,\nruntime mode/model, available slash commands, JetBrains `_meta.proxyConfig`.\nDrawer in the UI; CLI: `session-info \u003cid\u003e`; MCP: `get_session_summary`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCross-session search\u003c/b\u003e — full-text across every saved frame\u003c/summary\u003e\n\nClick a result to jump to that row in the timeline. CLI: `search \u003cpattern\u003e`\nwith grep-style exit codes (1 if no match).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eReplay\u003c/b\u003e — play/pause/speed/seek through a saved session\u003c/summary\u003e\n\nEvery frame is on screen from the start; a left-rail playhead marks the\ncurrent position and the timeline follows it as it runs (0.5×–8× speed via\nthe scrubber). CLI: `replay \u003cid\u003e` rebroadcasts over WebSocket on a fixed\nport for repeatable demos.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eExport / import\u003c/b\u003e — JSON dumps you can share or re-import\u003c/summary\u003e\n\nTwo engineers can debug the same capture without spinning up an editor.\nImported sessions appear in the picker tagged `IMPORTED`. `export` redacts\nauth headers and proxy tokens (including JetBrains `proxy_key`) by default\n— see [Security \u0026 privacy](#security--privacy).\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eMock agent / editor\u003c/b\u003e — record-replay primitives for CI\u003c/summary\u003e\n\n`mock-editor --script \u003cexport.json\u003e` drives a real agent with recorded editor\ntraffic (no IDE, no tokens burned); `mock-agent` does the inverse. Pair with\n`validate` and `stats --json` for headless spec/latency gating.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eRead-only MCP server\u003c/b\u003e — 13 tools so an AI agent can query your captures\u003c/summary\u003e\n\nTools: `list_sessions`, `get_session_summary`, `find_spec_violations`,\n`diff_sessions`, `search_messages`, and 8 more. Wire via `acp-devtools mcp`\nand add to your AI agent's MCP config.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConcurrent captures\u003c/b\u003e — multiple editor windows in one inspector tab\u003c/summary\u003e\n\nEvery capture registers in `~/.acp-devtools/active/\u003cpid\u003e.json` with an\nephemeral port. The session picker auto-discovers them — no port conflicts\neven with several chats open.\n\u003c/details\u003e\n\n## Quickstart\n\n### Install via npm\n\n```bash\nnpm install -g acp-devtools\n```\n\n`-g` is the recommended install — it puts `acp-devtools` on your `PATH`, which\nis how editors (Zed, JetBrains, Neovim) find it when they spawn the proxy as a\nsubprocess. Without it, every editor config has to use an absolute path.\n\nIf you only want to try the inspector once without installing, `npx` works too:\n\n```bash\nnpx acp-devtools ui                  # downloads on first run, slower start; cache path is not PATH-discoverable\n```\n\n### Install via Homebrew\n\n```bash\nbrew tap maksugr/tap\nbrew trust maksugr/tap     # required once — Homebrew 5+ blocks third-party taps by default\nbrew install acp-devtools\n```\n\n### Run the inspector\n\n```bash\nacp-devtools ui                      # → http://127.0.0.1:3737/ (auto-opens)\n```\n\nConnect your editor with `acp-devtools setup`, which writes the config with the\nabsolute binary path filled in:\n\n```bash\nacp-devtools setup --editor zed --write                  # Claude Code (default) in Zed\nacp-devtools setup junie --editor jetbrains --write      # any registry shortcut\nacp-devtools setup --editor zed --write -- npx -y @your-scope/your-acp   # any custom agent\n```\n\nFor Claude Code in Zed that's a one-line `agent_servers` entry — `acp-devtools`\ndetects it was spawned by an editor (stdin is a pipe) and runs\n`proxy --agent claude-code` internally:\n\n```json\n{\n    \"agent_servers\": {\n        \"Claude Code (via ACP Devtools)\": {\n            \"type\": \"custom\",\n            \"command\": \"/opt/homebrew/bin/acp-devtools\"\n        }\n    }\n}\n```\n\nSend a prompt → the proxy spawns the agent, and within a second the inspector\nshows the handshake:\n\n```\n┌─ SESSION #1 · LIVE ────────────────────────────────────┐\n│ #1  18:34:06  → OUT  REQ  initialize             id:0  │\n│ #2  18:34:06  ← IN   RSP  —                    +402ms  │\n│ #3  18:34:06  → OUT  REQ  session/new            id:1  │\n│ #4  18:34:08  ← IN   RSP  —                    +1.84s  │\n│ #5  18:34:15  → OUT  REQ  session/prompt         id:2  │\n│ #6  18:34:16  ← IN   STR  agent_message_chunk     ×42  │\n└────────────────────────────────────────────────────────┘\n```\n\nDrop `--write` to print the block instead of writing it. If you hand-edit the\nconfig and the editor reports \"agent command not found\", its GUI can't resolve\nthe binary — use the absolute path from `which acp-devtools` (what `setup`\nwrites).\n\nPer-editor setups — each covers Claude Code, Codex, Goose, OpenCode, and how to\nwrap a custom agent — plus a Claude Code multi-profile / auth recipe:\n\n- [Zed setup with every agent](examples/zed-config.md)\n- [JetBrains setup (WebStorm / IntelliJ / PyCharm / …)](examples/jetbrains-config.md)\n- [Claude Code multi-profile (personal vs work OAuth)](examples/claude-code-setup.md)\n\n## The inspector\n\nA vertical timeline of every frame plus a JSON detail panel. Frames stream in\nlive; clicking a row expands its payload, with latency annotations, stream\nclustering, spec badges, a performance waterfall, replay controls, and a\nsession diff view. Full tour — labels, detail tabs, perf dashboard, diff panel, shortcuts:\n**[docs/ui.md](docs/ui.md)**.\n\n## The CLI\n\nEvery UI control has a headless equivalent, colorized and grep/jq-friendly.\n\n```bash\nacp-devtools list                                  # saved sessions, newest first\nacp-devtools stats 23 --by-method                  # latency percentiles\nacp-devtools inspect 23 --kind req --grep prompt   # filtered timeline, in the terminal\nacp-devtools diff 23 41                             # what changed between two sessions\nacp-devtools \u003ccommand\u003e --help                       # grouped, colorized help\n```\n\nFull reference: **[docs/cli.md](docs/cli.md)**. Task-driven walkthroughs\n(headless debugging, A/B two agents, mock-based CI): **[docs/recipes.md](docs/recipes.md)**.\n\n## MCP\n\n`acp-devtools mcp` exposes saved captures to an AI agent (Claude Code, Claude\nDesktop, …) as thirteen read-only tools so you can ask it to investigate your own\ntraces — or wire up a new agent:\n\n\u003e \"find spec violations in the last 10 sessions\" ·\n\u003e \"compare p99 of `session/prompt` between WebStorm and Zed\" ·\n\u003e \"diff sessions 41 and 42 — what changed?\" ·\n\u003e \"add junie for zed\"\n\nSetup in one command (Claude Code as an example):\n\n```bash\nclaude mcp add acp-devtools -- acp-devtools mcp\n```\n\nStdio only; no network surface. Auth tokens and proxy keys are unconditionally\nredacted in every tool response — see [Security \u0026 privacy](#security--privacy).\n\nFull tool reference and setup variants for other MCP clients:\n**[docs/mcp.md](docs/mcp.md)**.\n\n## Supported editors \u0026 agents\n\nThe tables below cover the [ACP ecosystem directory](https://zed.dev/acp), with two verification levels:\n**verified** means we captured a full prompt turn through acp-devtools;\n**handshake** means the agent answered `initialize` / `session/new` through\nthe proxy and a full turn only needs an account for that agent. Every\nverified and handshake row links its proof twice: `playground` opens the\nactual capture in the [playground](#playground) in one click, `json` is the\nsame redacted export in [`fixtures/handshakes/`](fixtures/handshakes/) for\n`acp-devtools import` or your own tooling. \n\n**Using any of these is the same regardless of status.** `untested` means we\nhaven't captured it yet, not that it won't work. Any ACP agent runs through\n`acp-devtools setup --editor \u003czed|jetbrains\u003e -- \u003cits launch command\u003e` (or\n`proxy \u003claunch command\u003e`); the launch command is the agent's own ACP entry point\n(`goose acp`, `junie --acp=true`, `npx -y @scope/acp`, …). The handful that are\nregistry shortcuts — `acp-devtools agents` lists them — skip the command:\n`acp-devtools setup \u003cname\u003e --editor zed`.\n\nGot one working that's `untested`? Help flip the row: run\n[`fixtures/drive-full-turn.mjs`](fixtures/drive-full-turn.mjs) against it\n(`node fixtures/drive-full-turn.mjs \u003claunch command\u003e` — exit 0 means a full\nprompt turn worked; exit 3 means the agent answered the handshake but needs\nan account for a full turn) and [open an\nissue](https://github.com/maksugr/acp-devtools/issues) with an `acp-devtools\nexport` attached (auth tokens are redacted on export) — we'll mark the agent\nverified.\n\n### Editors\n\n| Editor                                                                 | ACP support                                                         | Status                                                                   |\n| ---------------------------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| [Zed](https://zed.dev/docs/ai/external-agents)                         | native                                                              | **verified** — Zed 1.3.5–1.5.4 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/zed-1.5.4-claude-code-0.43.0.json) · [json](fixtures/handshakes/zed-1.5.4-claude-code-0.43.0.json) · [setup](examples/zed-config.md)         |\n| [JetBrains IDEs](https://www.jetbrains.com/help/ai-assistant/acp.html) | native (AI Assistant)                                               | **verified** — WebStorm 2026.1.2 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/goose-1.37.0.json) · [json](fixtures/handshakes/goose-1.37.0.json) · [setup](examples/jetbrains-config.md) |\n| [Visual Studio Code](https://github.com/formulahendry/vscode-acp)      | `vscode-acp` extension                                              | untested                                                                 |\n| [Neovim](https://github.com/olimorris/codecompanion.nvim)              | CodeCompanion, [avante.nvim](https://github.com/yetone/avante.nvim) | untested                                                                 |\n| [Emacs](https://github.com/xenodium/agent-shell)                       | `agent-shell` package                                               | untested                                                                 |\n| [Obsidian](https://github.com/RAIT-09/obsidian-agent-client)           | Agent Client plugin                                                 | untested                                                                 |\n| [marimo](https://marimo.io)                                            | built into the notebook                                             | untested                                                                 |\n| [AionUi](https://github.com/iOfficeAI/AionUi)                          | desktop GUI                                                         | untested                                                                 |\n| [DeepChat](https://github.com/ThinkInAIXYZ/deepchat)                   | desktop chat app                                                    | untested                                                                 |\n| [Tidewave](https://tidewave.ai)                                        | web app                                                             | untested                                                                 |\n| [aizen](https://aizen.win)                                             | desktop app                                                         | untested                                                                 |\n| [Sidequery](https://sidequery.dev)                                     | browser-based, announced                                            | untested                                                                 |\n| [Web Browser (AI SDK)](https://zed.dev/acp/editor/web-browser)         | `@mcpc/acp-ai-provider`                                             | untested                                                                 |\n\n### Agents\n\n| Agent                                                                              | Status                                                                                                                    |\n| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |\n| [AgentPool](https://phil65.github.io/agentpool/advanced/acp-integration/)          | untested                                                                                                                  |\n| [Agoragentic](https://zed.dev/acp/agent/agoragentic-acp)                           | untested                                                                                                                  |\n| [Amp](https://ampcode.com)                                                         | handshake — amp-acp 0.8.1 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/amp-acp-0.8.1.json) · [json](fixtures/handshakes/amp-acp-0.8.1.json)                                                       |\n| [Augment Code](https://docs.augmentcode.com/cli/acp)                               | handshake — auggie 0.29.0 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/auggie-0.29.0.json) · [json](fixtures/handshakes/auggie-0.29.0.json)                                                       |\n| [Autohand Code](https://zed.dev/acp/agent/autohand)                                | untested                                                                                                                  |\n| [Blackbox AI](https://docs.blackbox.ai/features/blackbox-cli/introduction)         | untested                                                                                                                  |\n| [Claude Code](https://www.npmjs.com/package/@agentclientprotocol/claude-agent-acp) | **verified** — claude-agent-acp 0.37–0.44 · [playground](https://playground.acp-devtools.dev/?url=https://gist.githubusercontent.com/maksugr/0059be3aba62538c099ae96f0bf34bbb/raw/06a5d8c926d6ad99a410688a07f8e35bd89bac36/gistfile1.txt) · [json](https://gist.github.com/maksugr/0059be3aba62538c099ae96f0bf34bbb)                                          |\n| [Cline](https://cline.bot)                                                         | untested — CLI 3.0.24 exposes no ACP mode                                                                                 |\n| [Code Assistant](https://github.com/stippi/code-assistant)                         | untested                                                                                                                  |\n| [Codebuddy Code](https://zed.dev/acp/agent/codebuddy-code)                         | untested                                                                                                                  |\n| [Codex CLI](https://developers.openai.com/codex/cli)                               | handshake — codex-acp 0.16.0 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/codex-acp-0.16.0.json) · [json](fixtures/handshakes/codex-acp-0.16.0.json)                              |\n| [Cortex Code](https://zed.dev/acp/agent/cortex-code)                               | untested                                                                                                                  |\n| [Corust Agent](https://zed.dev/acp/agent/corust-agent)                             | untested                                                                                                                  |\n| [crow-cli](https://crow-ai.dev)                                                    | fails — 0.3.0 npm binary links Intel-Homebrew `libgc`, crashes on Apple Silicon                                           |\n| [Cursor](https://cursor.com/docs/cli/acp)                                          | **verified** — cursor-agent 2026.05.16 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/cursor-cli-2026.05.16.json) · [json](fixtures/handshakes/cursor-cli-2026.05.16.json)                |\n| [DeepAgents](https://github.com/langchain-ai/deepagents)                           | untested                                                                                                                  |\n| [DimCode](https://zed.dev/acp/agent/dimcode)                                       | untested                                                                                                                  |\n| [Dirac](https://zed.dev/acp/agent/dirac)                                           | untested                                                                                                                  |\n| [Docker cagent](https://github.com/docker/cagent)                                  | untested                                                                                                                  |\n| [Factory Droid](https://factory.ai)                                                | untested                                                                                                                  |\n| [fast-agent](https://fast-agent.ai/acp)                                            | untested                                                                                                                  |\n| [Gemini CLI](https://github.com/google-gemini/gemini-cli)                          | handshake — gemini-cli 0.46.0 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/gemini-cli-0.46.0.json) · [json](fixtures/handshakes/gemini-cli-0.46.0.json)                                               |\n| [GitHub Copilot](https://github.com/features/copilot)                              | handshake — copilot 1.0.61 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/copilot-cli-1.0.61.json) · [json](fixtures/handshakes/copilot-cli-1.0.61.json)                                                 |\n| [GLM Agent](https://zed.dev/acp/agent/glm-acp-agent)                               | untested                                                                                                                  |\n| [Goose](https://block.github.io/goose/docs/guides/acp-clients)                     | **verified** — goose 1.37.0 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/goose-1.37.0.json) · [json](fixtures/handshakes/goose-1.37.0.json) |\n| [Grok Build](https://zed.dev/acp/agent/grok-build)                                 | untested                                                                                                                  |\n| [JetBrains Junie](https://junie.jetbrains.com)                                     | **verified** — Junie CLI 26.6.15 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/junie-26.6.15.json) · [json](fixtures/handshakes/junie-26.6.15.json)                                                |\n| [Kilo](https://kilocode.ai)                                                        | untested                                                                                                                  |\n| [Kimi CLI](https://github.com/MoonshotAI/kimi-cli)                                 | handshake — Kimi Code CLI 1.47.0 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/kimi-code-cli-1.47.0.json) · [json](fixtures/handshakes/kimi-code-cli-1.47.0.json)                                         |\n| [Kiro CLI](https://kiro.dev/docs/cli/acp/)                                         | untested                                                                                                                  |\n| [Minion Code](https://github.com/femto/minion-code)                                | untested                                                                                                                  |\n| [Mistral Vibe](https://github.com/mistralai/mistral-vibe)                          | handshake — vibe 2.15.0 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/mistral-vibe-2.15.0.json) · [json](fixtures/handshakes/mistral-vibe-2.15.0.json)                                                   |\n| [Nova](https://zed.dev/acp/agent/nova)                                             | untested                                                                                                                  |\n| [OpenCode](https://opencode.ai)                                                    | handshake — OpenCode 1.17.4 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/opencode-1.17.4.json) · [json](fixtures/handshakes/opencode-1.17.4.json)                             |\n| [OpenHands](https://docs.openhands.dev/openhands/usage/run-openhands/acp)          | untested                                                                                                                  |\n| [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent)          | untested                                                                                                                  |\n| [Poolside](https://zed.dev/acp/agent/poolside)                                     | untested                                                                                                                  |\n| [Qoder CLI](https://docs.qoder.com/cli/acp)                                        | untested                                                                                                                  |\n| [Qwen Code](https://github.com/QwenLM/qwen-code)                                   | handshake — qwen-code 0.17.1 · [playground](https://playground.acp-devtools.dev/?url=https://raw.githubusercontent.com/maksugr/acp-devtools/main/fixtures/handshakes/qwen-code-0.17.1.json) · [json](fixtures/handshakes/qwen-code-0.17.1.json)                                                 |\n| [siGit Code](https://github.com/getsigit/sigit)                                    | untested                                                                                                                  |\n| [Stakpak](https://github.com/stakpak/agent)                                        | untested                                                                                                                  |\n| [VT Code](https://github.com/vinhnx/vtcode)                                        | fails — `vtcode acp` 0.52.8 exits silently (no response to `initialize`)                                                  |\n\n### Launch shortcuts\n\nThe built-in registry maps five common agents to ready commands. npm-based\nagents auto-install on first use via `npx -y …`; binary-based agents need a\none-time install. `acp-devtools agents` prints this list from the CLI.\n\n| Shortcut                  | What it runs                                   | Install                                          |\n| ------------------------- | ---------------------------------------------- | ------------------------------------------------ |\n| `claude-code` _(default)_ | `npx -y @agentclientprotocol/claude-agent-acp` | npx — automatic                                  |\n| `codex`                   | `npx -y @zed-industries/codex-acp`             | npx — automatic                                  |\n| `goose`                   | `goose acp`                                    | install Goose from \u003chttps://goose-docs.ai\u003e first |\n| `opencode`                | `opencode acp`                                 | `curl -fsSL https://opencode.ai/install \\| bash` |\n| `junie`                   | `junie --acp=true`                             | install Junie CLI from \u003chttps://junie.jetbrains.com/\u003e first |\n\nEvery other agent runs through the explicit form:\n`acp-devtools proxy \u003cyour-command\u003e [args…]`.\n\n## Architecture\n\n```\n   Editor (Zed / JetBrains / Neovim / VS via ReSharper)\n            │  ACP via stdio (newline-delimited JSON-RPC 2.0)\n            ▼\n   ┌─────────────────────────────────────────┐\n   │  acp-devtools proxy                      │\n   │   spawns the agent                       │\n   │   captures every frame in both directions│\n   │   writes ~/.acp-devtools/captures.db     │\n   │   broadcasts on a local WebSocket        │\n   │   registers ~/.acp-devtools/active/      │\n   └──────────────┬──────────────────────────┘\n                  │ stdio\n                  ▼\n        ACP agent (claude-agent-acp, codex-acp, …)\n\n   Browser ◄── HTTP ──── acp-devtools ui (3737)\n                          serves the React bundle + discovers live captures\n```\n\nNeither side of the pipe knows the proxy exists. Multiple captures (one chat per\neditor window) coexist on independent ephemeral ports and all appear in the\ninspector's session picker.\n\n## Security \u0026 privacy\n\nACP traffic carries real secrets. Anything sent on the wire is captured\nverbatim into `captures.db`, including the JetBrains AI gateway token\nWebStorm puts on every `initialize`. `acp-devtools` is local-first by\ndesign — nothing leaves your machine unless you choose to share an export.\nThis section spells out what's at risk and what the tool does about it.\n\n### What ACP captures contain\n\n| Source                                                                   | Lives in                                                    | Sensitive?                                         |\n| ------------------------------------------------------------------------ | ----------------------------------------------------------- | -------------------------------------------------- |\n| `initialize._meta.proxyConfig.proxies[].proxy.headers`                   | every WebStorm session                                      | **YES** — JetBrains LLM gateway auth (`proxy_key`) |\n| HTTP-style `Authorization` / `X-Api-Key` / `Cookie` headers in any field | uncommon but possible in custom agents / `_meta` extensions | **YES**                                            |\n| `fs/read_text_file` results                                              | every session that opens files                              | depends — proprietary source vs. public code       |\n| Prompts you typed and model responses                                    | every session                                               | depends — internal context vs. generic question    |\n| Method names, latencies, frame counts, schema shapes                     | every session                                               | no — useful for bug reports                        |\n\nThe capture file stays on your machine; nothing in the tool uploads it.\nThe risk surface is when **you** share an export — and that's what default\nredaction targets.\n\n### `acp-devtools export` — redacts by default\n\n```bash\nacp-devtools export 21 \u003e capture.json    # safe-by-default for sharing\nacp-devtools export 21 --raw             # opt-in: keep everything (self-debug only)\n```\n\nWhat gets replaced with `\u003cREDACTED\u003e`: every string value under any\n`proxyConfig.proxies[*].proxy.headers.*` subtree (catches future JetBrains\nfields, not just `proxy_key`), plus standard HTTP auth headers\n(`Authorization`, `X-Api-Key`, `Cookie`, …) anywhere in the JSON. Full list\nlives in [`packages/core/src/storage/redact.ts`](packages/core/src/storage/redact.ts).\n\nRedaction rewrites **both** `payload` (parsed) and `raw` (wire string), so\nthe secret can't leak via either field. A summary lands on stderr:\n`redacted N field(s) across M message(s) — re-run with --raw to keep them`.\n\nThe same default applies everywhere output is likely to leave your machine:\n`export`, the UI's download button, every MCP tool response, `diff`, and\n`session-info` (the last two take the same `--raw` opt-out). Two surfaces\nstay raw on purpose: `inspect` prints the actual wire bytes for local\ntriage, and the local HTTP API the UI reads\n(`GET /api/sessions/:id/messages`) returns frames as captured — treat both\nlike the database file itself, not like an export.\n\n### What it does **not** redact (your call)\n\nFile contents loaded via `fs/read_text_file` and the prompts / responses\nstay as-is. There's no reliable heuristic for \"is this code proprietary\" —\nthat's a judgement call. Before sharing, audit with:\n\n```bash\nacp-devtools inspect 21 --kind ntf  # all notifications (responses, streaming, tool calls)\nacp-devtools inspect 21 --grep proxy_key  # see which frames carry tokens (inspect shows raw bytes)\n```\n\nIf something in those fields shouldn't ship, either drop the offending\nmessages with `jq` before sharing, or capture a smaller reproducer with\nfresh sessions.\n\n### Sharing for a bug report\n\nA typical Zed / agent-author bug report:\n\n```bash\nacp-devtools export 21 \u003e acp-bug.json     # auto-redacted\nacp-devtools inspect 21 --grep \u003csecret\u003e   # double-check nothing slipped through\n# Attach acp-bug.json to the GitHub issue.\n```\n\nThe [playground](#playground) lets the reviewer drop `acp-bug.json` into\na browser and see the same timeline you saw — no install on their side.\n\n### Reporting a security issue\n\nEmail security concerns to \u003cmaksugr@gmail.com\u003e with subject prefix\n`[acp-devtools security]`. Please don't open a public issue for actual\ndisclosures.\n\n## Playground\n\nThe inspector also runs as a static page at\n[**playground.acp-devtools.dev**](https://playground.acp-devtools.dev) —\ndrop a `session.json` export (or a public gist URL) into a browser and\nyou get the same timeline you'd get locally. No backend; nothing\nuploaded to any server we run (we don't run any). Built from this repo\nwith `VITE_PLAYGROUND=1` and published to GitHub Pages on every push to\n`main`.\n\nThis [gist sample](https://playground.acp-devtools.dev/?url=https://gist.githubusercontent.com/maksugr/0059be3aba62538c099ae96f0bf34bbb/raw/06a5d8c926d6ad99a410688a07f8e35bd89bac36/gistfile1.txt)\npre-loads a real WebStorm ↔ claude-agent-acp session (97 frames: handshake,\na tool call behind a permission dialog, a cancelled turn) — the same capture\n[Anatomy of an ACP session](docs/session-anatomy.md) walks through frame by\nframe. Here's how that flow works: the playground fetches the JSON export\nfrom the gist URL and renders it client-side — the gist is the storage,\nGitHub serves it over CORS, the playground just renders.\n\n## Documentation\n\n- [Anatomy of an ACP session](docs/session-anatomy.md) — how to read a capture: handshake, prompt turn, what broken looks like\n- [CLI reference](docs/cli.md) — every command, flag, and sample output\n- [The inspector (UI)](docs/ui.md) — timeline, detail panel, perf, diff\n- [MCP server](docs/mcp.md) — tools and setup\n- [Recipes](docs/recipes.md) — headless debugging, diffing, mock-based testing\n- [Changelog](CHANGELOG.md) — what shipped in each release\n- [Contributing](CONTRIBUTING.md) — build from source, layout, conventions\n\n---\n\nCo-developed with [Claude Code](https://claude.com/claude-code) (Opus). Pair-programmed,\nbut every line was read, shaped, and handcrafted by an experienced human, with love 🖤\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaksugr%2Facp-devtools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaksugr%2Facp-devtools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaksugr%2Facp-devtools/lists"}