{"id":47185866,"url":"https://github.com/beyond5959/acp-adapter","last_synced_at":"2026-04-09T04:05:10.267Z","repository":{"id":340905442,"uuid":"1167443324","full_name":"beyond5959/acp-adapter","owner":"beyond5959","description":"Bridging Codex \u0026 Claude Code to Agent Client Protocol (ACP) with Go.","archived":false,"fork":false,"pushed_at":"2026-03-31T06:56:24.000Z","size":2714,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-03T01:44:57.393Z","etag":null,"topics":["acp","agent-client-protocol","claude-code","codex","codex-cli"],"latest_commit_sha":null,"homepage":"","language":"Go","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/beyond5959.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-26T09:51:12.000Z","updated_at":"2026-03-31T06:55:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beyond5959/acp-adapter","commit_stats":null,"previous_names":["beyond5959/codex-acp","beyond5959/acp-adapter"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/beyond5959/acp-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyond5959%2Facp-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyond5959%2Facp-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyond5959%2Facp-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyond5959%2Facp-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beyond5959","download_url":"https://codeload.github.com/beyond5959/acp-adapter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beyond5959%2Facp-adapter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31584839,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"online","status_checked_at":"2026-04-09T02:00:06.848Z","response_time":112,"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","claude-code","codex","codex-cli"],"created_at":"2026-03-13T09:09:20.894Z","updated_at":"2026-04-09T04:05:10.252Z","avatar_url":"https://github.com/beyond5959.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ACP adapter for Codex, Claude Code, and Pi\n\n[![CI](https://github.com/beyond5959/acp-adapter/actions/workflows/go.yml/badge.svg)](https://github.com/beyond5959/acp-adapter/actions)\n[![License](https://img.shields.io/github/license/beyond5959/acp-adapter)](LICENSE)\n[![Go Version](https://img.shields.io/badge/Go-1.24+-blue)](https://go.dev)\n[![Go Report Card](https://goreportcard.com/badge/github.com/beyond5959/acp-adapter)](https://goreportcard.com/report/github.com/beyond5959/acp-adapter)\n\n\u003cimg src=\"docs/assets/acp-adapter.png\" alt=\"acp-adapter promo\" width=\"400\"\u003e\n\n`acp-adapter` is a Go ACP (Agent Client Protocol) adapter that lets ACP clients drive multiple downstream agent backends over the [ACP protocol](https://agentclientprotocol.com/):\n\n| Backend | Downstream official channel | Standalone flag | Library package | Notes |\n|------|------|------|------|------|\n| Codex | `codex app-server` over stdio JSON-RPC | `--adapter codex` | [`pkg/codexacp`](./pkg/codexacp) | Most complete backend, including MCP routing. |\n| Claude Code | `claude -p ... --output-format stream-json` | `--adapter claude` | [`pkg/claudeacp`](./pkg/claudeacp) | Machine-readable Claude CLI bridge. |\n| Pi | `pi --mode rpc` over official RPC JSON lines | `--adapter pi` | [`pkg/piacp`](./pkg/piacp) | Official Pi RPC bridge with session load/list and ACP permission gate. |\n\n## Usage Modes\n\nThis component supports two integration models:\n\n| Mode | Use Case | Entry Point |\n|------|----------|-------------|\n| **Standalone** (process) | Configure a binary in Zed or other ACP clients | [`cmd/acp`](./cmd/acp) |\n| **Library** (embedded) | Host ACP runtime inside your Go service | [`pkg/codexacp`](./pkg/codexacp), [`pkg/claudeacp`](./pkg/claudeacp), [`pkg/piacp`](./pkg/piacp) |\n\n## Standalone Usage\n\n### Installation\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/beyond5959/acp-adapter/master/install.sh | sh\n```\n\n### Quick Start\n\n```bash\n# Codex backend (default)\nacp-adapter --adapter codex\n\n# Claude backend\nacp-adapter --adapter claude\n\n# Pi backend\nacp-adapter --adapter pi --pi-provider openai-codex --pi-model gpt-5.4-mini\n```\n\nPi mode expects a working `pi` CLI on `PATH` or `--pi-bin`. Useful Pi-specific flags:\n\n- `--pi-provider` / `PI_PROVIDER`\n- `--pi-model` / `PI_MODEL`\n- `--pi-session-dir` / `PI_SESSION_DIR`\n- `--pi-disable-gate` / `PI_DISABLE_GATE`\n\n### ACP Client Config\n\n```json\n{\n  \"agent_servers\": {\n    \"acp-adapter\": {\n      \"command\": \"/usr/local/bin/acp-adapter\",\n      \"args\": [\"--adapter\", \"pi\", \"--pi-provider\", \"openai-codex\", \"--pi-model\", \"gpt-5.4-mini\"]\n    }\n  }\n}\n```\n\nSwap `pi` for `codex` or `claude` if you want a different backend.\n\n## Library Usage\n\nThe three runtime packages expose aligned entry points: `DefaultRuntimeConfig`, `RunStdio`, and `NewEmbeddedRuntime`.\n\n```go\nimport \"github.com/beyond5959/acp-adapter/pkg/piacp\"\n\n// Stdio mode\ncfg := piacp.DefaultRuntimeConfig()\ncfg.DefaultProvider = \"openai-codex\"\ncfg.DefaultModel = \"gpt-5.4-mini\"\nerr := piacp.RunStdio(ctx, cfg, os.Stdin, os.Stdout, os.Stderr)\n\n// Embedded mode\nrt := piacp.NewEmbeddedRuntime(cfg)\nrt.Start(ctx)\ndefer rt.Close()\nresp, err := rt.ClientRequest(ctx, msg)\n```\n\nUse [`pkg/codexacp`](./pkg/codexacp) for Codex and [`pkg/claudeacp`](./pkg/claudeacp) for Claude; the runtime shape is the same, while config fields stay backend-specific.\n\n## Codex ACP Support\n\nThis section is intentionally based on the current code in [`internal/acp/server.go`](./internal/acp/server.go) and [`internal/acp/types.go`](./internal/acp/types.go).\n\n| ACP surface | Support | Notes |\n|------|------|------|\n| `initialize` | Yes | Returns `protocolVersion=1` and ACP capability flags. |\n| `authenticate` | Yes | Supports `codex_api_key`, `openai_api_key`, `chatgpt_subscription`. |\n| `session/new` | Yes | Creates a Codex-backed session/thread. |\n| `session/prompt` | Yes | Main turn entry; slash commands are routed here too. |\n| `session/cancel` | Yes | Cancels the active Codex turn. |\n| `session/list` | Yes | Lists Codex-backed sessions. |\n| `session/load` | Yes | Loads a historical Codex session. |\n| `session/set_config_option` | Yes | Currently supports `model` and `thought_level`. |\n| `session/update` | Yes | Streams prompt execution updates back to the ACP client. |\n| `session/request_permission` | Yes | Used for command/file/network/MCP approvals. |\n| `fs/read_text_file` | Partial | Used only when the client exposes it, for mentions and diff reconstruction. |\n| `fs/write_text_file` | Partial | Used only when `PATCH_APPLY_MODE=acp_fs`. |\n\n| `session/update.type` | Standard `update.sessionUpdate` | Support | Notes |\n|------|------|------|------|\n| `message` | `agent_message_chunk` / `user_message_chunk` | Yes | Main text streaming path. |\n| `tool_call_update` | `tool_call_update` | Yes | Tool lifecycle, approvals, command output, diff, text, and image content. |\n| `usage_update` | `usage_update` | Yes | Emitted from Codex `thread/tokenUsage/updated`; currently maps `used=tokenUsage.last.inputTokens` and `size=modelContextWindow`. |\n| `config_options_update` | `config_options_update` | Yes | Emitted after `session/set_config_option`. |\n| `plan` | `plan` | Yes | Emitted from Codex plan events. |\n| `available_commands_update` | `available_commands_update` | Yes | Publishes the Codex slash-command directory. |\n| `reasoning` | `agent_thought_chunk` | Yes | Reasoning output is exposed as ACP thought chunks. |\n| `status` | no dedicated standard kind | Partial | Present on the wire, but the standard envelope currently falls back to `agent_thought_chunk`. |\n\n| ACP capability flag | Support | Notes |\n|------|------|------|\n| `loadSession` | Yes | Advertised from `initialize`. |\n| `sessionCapabilities.list` | Yes | Advertised when the Codex backend supports session listing. |\n| `promptCapabilities.image` | Yes | Advertised. |\n| `promptCapabilities.audio` | No | Advertised as unsupported. |\n| `promptCapabilities.embeddedContext` | Yes | Advertised. |\n| `mcpCapabilities.http` | No | MCP is bridged through Codex command/tool paths, not ACP HTTP transport. |\n| `mcpCapabilities.sse` | No | MCP is bridged through Codex command/tool paths, not ACP SSE transport. |\n\n## Pi ACP Support\n\nThis section is intentionally based on the current code in [`internal/acp/server.go`](./internal/acp/server.go), [`internal/pi/client.go`](./internal/pi/client.go), and [`internal/acp/types.go`](./internal/acp/types.go).\n\nPi mode currently publishes these slash commands: `/review`, `/review-branch`, `/review-commit`, `/init`, `/compact`, `/logout`.\n\n| ACP surface | Support | Notes |\n|------|------|------|\n| `initialize` | Yes | Returns `protocolVersion=1` and ACP capability flags. |\n| `authenticate` | Yes | Supports `pi`; also restores adapter-side Pi availability after `/logout`. |\n| `session/new` | Yes | Creates a Pi-backed session through official `pi --mode rpc`. |\n| `session/prompt` | Yes | Main turn entry; slash commands are routed here too. |\n| `session/cancel` | Yes | Cancels the active Pi turn. |\n| `session/list` | Yes | Lists Pi session files from the configured or default Pi session directory. |\n| `session/load` | Yes | Loads a historical Pi session file, replays history, and allows continued prompting. |\n| `session/set_config_option` | Yes | Currently supports `model` and `thought_level`. |\n| `session/update` | Yes | Streams Pi prompt execution updates back to the ACP client. |\n| `session/request_permission` | Yes | Used for Pi `bash` / `write` / `edit` permission gate requests. |\n| `fs/read_text_file` | Partial | Used only when the client exposes it, for mentions and embedded context. |\n| `fs/write_text_file` | No | Current Pi bridge does not use ACP fs patch apply; writes stay on Pi tool paths behind permission gate. |\n\n| `session/update.type` | Standard `update.sessionUpdate` | Support | Notes |\n|------|------|------|------|\n| `message` | `agent_message_chunk` / `user_message_chunk` | Yes | Main text streaming path. |\n| `tool_call_update` | `tool_call_update` | Yes | Tool lifecycle, approvals, command output, and tool text output from Pi RPC events. |\n| `usage_update` | `usage_update` | Yes | Best-effort mapping from Pi `get_session_stats`; emitted when stats are available in time. |\n| `config_options_update` | `config_options_update` | Yes | Emitted after `session/set_config_option`. |\n| `plan` | `plan` | No | Current Pi bridge does not emit ACP plan snapshots. |\n| `available_commands_update` | `available_commands_update` | Yes | Publishes the Pi slash-command directory and refreshes it on auth changes. |\n| `reasoning` | `agent_thought_chunk` | Yes | Pi `thinking_delta` is exposed as ACP thought chunks. |\n| `status` | no dedicated standard kind | Partial | Used for review lifecycle and backend/gate diagnostics; no dedicated standard envelope kind exists yet. |\n\n| ACP capability flag | Support | Notes |\n|------|------|------|\n| `loadSession` | Yes | Advertised from `initialize`. |\n| `sessionCapabilities.list` | Yes | Advertised in Pi mode. |\n| `promptCapabilities.image` | Yes | Advertised. |\n| `promptCapabilities.audio` | No | Advertised as unsupported. |\n| `promptCapabilities.embeddedContext` | Yes | Advertised. |\n| `mcpCapabilities.http` | No | Pi mode does not bridge ACP HTTP MCP transport. |\n| `mcpCapabilities.sse` | No | Pi mode does not bridge ACP SSE MCP transport. |\n\nCurrent Pi-specific gaps relative to Codex:\n\n- No `/mcp` command or MCP list/call/oauth routing.\n- No archived session pagination in `session/list`.\n- `/review` is simulated through normal Pi prompts plus synthetic review lifecycle events, not a native Pi review RPC.\n- Pi custom `get_commands` and generic `extension_ui_request` flows are not yet bridged to ACP.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyond5959%2Facp-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeyond5959%2Facp-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeyond5959%2Facp-adapter/lists"}