{"id":51228934,"url":"https://github.com/hecatehq/codex-acp-adapter","last_synced_at":"2026-06-28T14:01:50.840Z","repository":{"id":365604453,"uuid":"1272898692","full_name":"hecatehq/codex-acp-adapter","owner":"hecatehq","description":"ACP adapter for running Codex-compatible coding agents over stdio","archived":false,"fork":false,"pushed_at":"2026-06-18T05:09:35.000Z","size":25,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T05:15:07.587Z","etag":null,"topics":["acp","adapter","codex","coding-agent"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hecatehq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","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-06-18T03:13:38.000Z","updated_at":"2026-06-18T05:09:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hecatehq/codex-acp-adapter","commit_stats":null,"previous_names":["hecatehq/codex-acp-adapter"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hecatehq/codex-acp-adapter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hecatehq%2Fcodex-acp-adapter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hecatehq%2Fcodex-acp-adapter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hecatehq%2Fcodex-acp-adapter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hecatehq%2Fcodex-acp-adapter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hecatehq","download_url":"https://codeload.github.com/hecatehq/codex-acp-adapter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hecatehq%2Fcodex-acp-adapter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34890795,"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-28T02:00:05.809Z","response_time":54,"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","adapter","codex","coding-agent"],"created_at":"2026-06-28T14:01:49.347Z","updated_at":"2026-06-28T14:01:50.834Z","avatar_url":"https://github.com/hecatehq.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# codex-acp-adapter\n\nNeutral Go ACP adapter for Codex-compatible coding agents.\n\nThis repository provides a Go ACP adapter for Codex-compatible coding agents. It\nruns as a small, auditable binary that speaks ACP over stdio. The adapter can\nrun Codex CLI prompts through its native command bridge. Hecate integration is\ncovered by release-binary smoke tests; deeper vendor-native parity remains\ntracked as future work.\n\n## Goals\n\n- Speak standard Agent Client Protocol over stdio.\n- Keep the adapter independent from Hecate internals.\n- Avoid package-manager launchers, shell wrappers, and broad environment\n  inheritance.\n- Preserve the important behavior exposed by the previous Codex ACP adapter:\n  sessions, auth, model/config options, permission requests, MCP servers,\n  tool updates, terminal output, slash commands, review/init workflows, and\n  cancellation.\n- Ship deterministic, checksum-verified, provenance-attested Go release\n  binaries.\n\n## Current Status\n\nImplemented:\n\n- stdlib-only JSON-RPC/NDJSON ACP transport scaffold\n- `initialize` response with adapter metadata\n- structured errors for unimplemented methods\n- source-review notes for the previous adapter behavior\n- unit tests for the protocol scaffold\n- `doctor` command for probing the local Codex binary boundary\n- process-backed runtime launcher seam\n- subprocess JSON-RPC client for ACP-style stdio runtime bridges\n- ACP initialize client for subprocess runtime negotiation\n- typed ACP session lifecycle calls for subprocess runtimes\n- ACP server-to-runtime bridge for session methods and streamed updates\n- runtime host seam that launches, initializes, and exposes the bridged child\n- protocol forwarding for session load, resume, fork, list, delete, and\n  MCP-over-ACP message payloads\n- command-backed native Codex CLI session path using `codex exec`\n- ACP model, reasoning, sandbox, approval-policy, and web-search config\n  options for the command-backed path\n- per-session ACP HTTP and stdio MCP server config propagation into Codex CLI\n  `-c mcp_servers.\u003cname\u003e=...` overrides\n- in-memory command-backed session load/resume/fork plus bounded transcript\n  replay for multi-turn continuity while the adapter process is alive\n- command-backed `session/list` metadata, `config_option_update`\n  notifications for config changes, and `session_info_update` notifications\n  when transcript metadata changes\n- command-backed `/review` advertisement and mapping to `codex review\n  --uncommitted`, plus `/init` advertisement through the normal `codex exec`\n  prompt path\n- Codex `exec --json` stream translation into ACP assistant text, reasoning,\n  tool-call, usage, and terminal stop-reason updates, including provider-native\n  shell, file, patch, web, MCP, image, plan, TODO, goal, and review tool\n  classifications, plus generic command `tool_call` activity for the native\n  Codex process\n- ACP `authenticate` mapped to the native `codex login` command\n- ACP `logout` mapped to the native `codex logout` command\n- CI and tag-driven release packaging for checksum-verified,\n  provenance-attested binaries\n\nNot implemented yet:\n\n- vendor-specific durable/native persistent session semantics across adapter\n  process restarts\n- deeper provider-native permission response edge cases beyond parsed request\n  mapping and the selected Codex sandbox / approval policy\n- vendor-native MCP tool permission and connection-lifecycle mapping beyond\n  passing per-session MCP server config into Codex\n- deeper provider-native slash-command/review semantics beyond the\n  adapter-owned `/review` and `/init` command surface\n- runtime config/auth/model discovery\n- draft ACP RFD surfaces documented as future work in `docs/STABLE_READINESS.md`\n\n## Development\n\nShared ACP transport, runtime JSON-RPC, bridge, host, process, doctor runner,\nand fake-runtime test code lives in\n[acp-adapter-kit](https://github.com/hecatehq/acp-adapter-kit). Keep this repo\nfocused on the Codex-specific CLI boundary, doctor defaults, docs, release\nworkflow, and vendor behavior.\n\nThe binary remains the primary integration mode. Hosts that need an embedded\nadapter can import `github.com/hecatehq/codex-acp-adapter/codexadapter` to build\nthe same ACP server, info/options, CLI spec, config options, environment\nallowlists, and Codex prompt command without shelling out to\n`codex-acp-adapter`. The embedded path still launches the underlying `codex` CLI\nfor prompts; it only removes the extra adapter process boundary.\n\n```sh\nmake release-check\nmake snapshot\ngo test ./...\ngo test -race ./...\ngo vet ./...\ngo run ./cmd/codex-acp-adapter --version\ngo run ./cmd/codex-acp-adapter doctor\n```\n\nSee [docs/TESTING.md](docs/TESTING.md) for what is covered today and what still\nneeds production-grade/deeper vendor-native parity coverage.\nSee [docs/RELEASE.md](docs/RELEASE.md) for the tag-driven release flow.\nSee [docs/STABLE_READINESS.md](docs/STABLE_READINESS.md) for the gate before a\nstable adapter tag.\n\n## CLI Contract\n\nThe binary uses Cobra for human commands, but the root command with no arguments\nis reserved for ACP stdio. Do not add default logging, banners, usage output, or\nprompts to the no-argument path; stdout is the protocol stream.\n\nUse `doctor` before wiring this adapter into an ACP host. It resolves the Codex\nbinary, runs a fixed-argv version probe through the hardened process runner, and\nreports selected environment variable presence without printing secret values.\nUse `--binary` to point at a non-default Codex executable and `--json` for\nmachine-readable output.\n\nBy default, the root ACP server owns lightweight ACP sessions and runs each\nprompt through `codex exec` in the session workspace. The command-backed path\nexposes ACP config options for model, reasoning effort, Codex sandbox mode,\nCodex approval policy including the explicit bypass mode, and Codex live web\nsearch, translates session MCP servers into temporary Codex `mcp_servers`\nconfig overrides, passes only provider-specific environment variables through\nthe shared process runner, and runs Codex with `exec --json`. Codex command\napprovals are governed by the selected sandbox and approval policy plus\npermission events emitted by the Codex JSONL stream. Known Codex JSONL events are\ntranslated into ACP assistant text, reasoning, tool-call, permission-request,\nand usage updates; unknown JSONL events are ignored rather than shown as raw\nchat text. A generic `tool_call` still wraps the native Codex process execution\nso hosts can show the outer command boundary. The session state is in-memory:\n`session/load`,\n`session/resume`, and `session/fork` work while the adapter process is alive,\n`session/list` returns the in-memory session metadata, and later prompts receive\na bounded transcript prelude so command-backed turns keep conversational context\nwithout claiming vendor-native durable history. `session/close` cancels active\nwork and frees that in-memory session state; `session/delete` is the\ndestructive cleanup path hosts should use when deleting the owning chat/session.\nConfig changes return the current config option list and publish\n`config_option_update` notifications.\nCompleted command-backed prompts publish `session_info_update` notifications\nwith the in-memory title and updated timestamp when transcript metadata changes.\nThe adapter advertises `/review` and `/init` as ACP available commands:\n`/review` maps to Codex's native `review --uncommitted` command, while `/init`\nis passed through `codex exec` as a normal Codex slash prompt so Codex can\ninspect the workspace and create or update repository agent instructions.\nThe adapter advertises one ACP auth method (`agent-login`): ACP\n`authenticate` maps to `codex login`, and ACP `logout` maps to `codex logout`.\n\nThe root ACP server can also launch an explicit subprocess-backed ACP runtime\nwith `--runtime-binary`, `--runtime-workdir`, and repeated `--runtime-arg`\nflags. That runtime process receives only the Codex adapter's explicit\nenvironment allowlist (`PATH`, `HOME`, `XDG_CONFIG_HOME`, `TMPDIR`,\n`CODEX_HOME`, `OPENAI_API_KEY`, and `OPENAI_BASE_URL`); the parent environment\nis not inherited wholesale. Runtime flags override the native command-backed\npath and are mostly useful for protocol parity testing.\n\n## Source Review\n\nBefore implementing the real bridge, read [docs/SOURCE_REVIEW.md](docs/SOURCE_REVIEW.md).\nIt records historical package/source behavior that this project needs to\npreserve or deliberately replace.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhecatehq%2Fcodex-acp-adapter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhecatehq%2Fcodex-acp-adapter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhecatehq%2Fcodex-acp-adapter/lists"}