codex-acp-adapter

Neutral Go ACP adapter for Codex-compatible coding agents.

This repository provides a Go ACP adapter for Codex-compatible coding agents. It runs as a small, auditable binary that speaks ACP over stdio. The adapter can run Codex CLI prompts through its native command bridge. Hecate integration is covered by release-binary smoke tests; deeper vendor-native parity remains tracked as future work.

Goals

• Speak standard Agent Client Protocol over stdio.
• Keep the adapter independent from Hecate internals.
• Avoid package-manager launchers, shell wrappers, and broad environment inheritance.
• Preserve the important behavior exposed by the previous Codex ACP adapter: sessions, auth, model/config options, permission requests, MCP servers, tool updates, terminal output, slash commands, review/init workflows, and cancellation.
• Ship deterministic, checksum-verified, provenance-attested Go release binaries.

Current Status

Implemented:

• stdlib-only JSON-RPC/NDJSON ACP transport scaffold
• initialize response with adapter metadata
• structured errors for unimplemented methods
• source-review notes for the previous adapter behavior
• unit tests for the protocol scaffold
• doctor command for probing the local Codex binary boundary
• process-backed runtime launcher seam
• subprocess JSON-RPC client for ACP-style stdio runtime bridges
• ACP initialize client for subprocess runtime negotiation
• typed ACP session lifecycle calls for subprocess runtimes
• ACP server-to-runtime bridge for session methods and streamed updates
• runtime host seam that launches, initializes, and exposes the bridged child
• protocol forwarding for session load, resume, fork, list, delete, and MCP-over-ACP message payloads
• command-backed native Codex CLI session path using codex exec
• ACP model, reasoning, sandbox, approval-policy, and web-search config options for the command-backed path
• per-session ACP HTTP and stdio MCP server config propagation into Codex CLI -c mcp_servers.<name>=... overrides
• in-memory command-backed session load/resume/fork plus bounded transcript replay for multi-turn continuity while the adapter process is alive
• command-backed session/list metadata, config_option_update notifications for config changes, and session_info_update notifications when transcript metadata changes
• command-backed /review advertisement and mapping to codex review --uncommitted, plus /init advertisement through the normal codex exec prompt path
• Codex exec --json stream translation into ACP assistant text, reasoning, tool-call, usage, and terminal stop-reason updates, including provider-native shell, file, patch, web, MCP, image, plan, TODO, goal, and review tool classifications, plus generic command tool_call activity for the native Codex process
• ACP authenticate mapped to the native codex login command
• ACP logout mapped to the native codex logout command
• CI and tag-driven release packaging for checksum-verified, provenance-attested binaries

Not implemented yet:

• vendor-specific durable/native persistent session semantics across adapter process restarts
• deeper provider-native permission response edge cases beyond parsed request mapping and the selected Codex sandbox / approval policy
• vendor-native MCP tool permission and connection-lifecycle mapping beyond passing per-session MCP server config into Codex
• deeper provider-native slash-command/review semantics beyond the adapter-owned /review and /init command surface
• runtime config/auth/model discovery
• draft ACP RFD surfaces documented as future work in docs/STABLE_READINESS.md

Development

Shared ACP transport, runtime JSON-RPC, bridge, host, process, doctor runner, and fake-runtime test code lives in acp-adapter-kit. Keep this repo focused on the Codex-specific CLI boundary, doctor defaults, docs, release workflow, and vendor behavior.

The binary remains the primary integration mode. Hosts that need an embedded adapter can import github.com/hecatehq/codex-acp-adapter/codexadapter to build the same ACP server, info/options, CLI spec, config options, environment allowlists, and Codex prompt command without shelling out to codex-acp-adapter. The embedded path still launches the underlying codex CLI for prompts; it only removes the extra adapter process boundary.

make release-check
make snapshot
go test ./...
go test -race ./...
go vet ./...
go run ./cmd/codex-acp-adapter --version
go run ./cmd/codex-acp-adapter doctor

See docs/TESTING.md for what is covered today and what still needs production-grade/deeper vendor-native parity coverage. See docs/RELEASE.md for the tag-driven release flow. See docs/STABLE_READINESS.md for the gate before a stable adapter tag.

CLI Contract

The binary uses Cobra for human commands, but the root command with no arguments is reserved for ACP stdio. Do not add default logging, banners, usage output, or prompts to the no-argument path; stdout is the protocol stream.

Use doctor before wiring this adapter into an ACP host. It resolves the Codex binary, runs a fixed-argv version probe through the hardened process runner, and reports selected environment variable presence without printing secret values. Use --binary to point at a non-default Codex executable and --json for machine-readable output.

By default, the root ACP server owns lightweight ACP sessions and runs each prompt through codex exec in the session workspace. The command-backed path exposes ACP config options for model, reasoning effort, Codex sandbox mode, Codex approval policy including the explicit bypass mode, and Codex live web search, translates session MCP servers into temporary Codex mcp_servers config overrides, passes only provider-specific environment variables through the shared process runner, and runs Codex with exec --json. Codex command approvals are governed by the selected sandbox and approval policy plus permission events emitted by the Codex JSONL stream. Known Codex JSONL events are translated into ACP assistant text, reasoning, tool-call, permission-request, and usage updates; unknown JSONL events are ignored rather than shown as raw chat text. A generic tool_call still wraps the native Codex process execution so hosts can show the outer command boundary. The session state is in-memory: session/load, session/resume, and session/fork work while the adapter process is alive, session/list returns the in-memory session metadata, and later prompts receive a bounded transcript prelude so command-backed turns keep conversational context without claiming vendor-native durable history. session/close cancels active work and frees that in-memory session state; session/delete is the destructive cleanup path hosts should use when deleting the owning chat/session. Config changes return the current config option list and publish config_option_update notifications. Completed command-backed prompts publish session_info_update notifications with the in-memory title and updated timestamp when transcript metadata changes. The adapter advertises /review and /init as ACP available commands: /review maps to Codex's native review --uncommitted command, while /init is passed through codex exec as a normal Codex slash prompt so Codex can inspect the workspace and create or update repository agent instructions. The adapter advertises one ACP auth method (agent-login): ACP authenticate maps to codex login, and ACP logout maps to codex logout.

The root ACP server can also launch an explicit subprocess-backed ACP runtime with --runtime-binary, --runtime-workdir, and repeated --runtime-arg flags. That runtime process receives only the Codex adapter's explicit environment allowlist (PATH, HOME, XDG_CONFIG_HOME, TMPDIR, CODEX_HOME, OPENAI_API_KEY, and OPENAI_BASE_URL); the parent environment is not inherited wholesale. Runtime flags override the native command-backed path and are mostly useful for protocol parity testing.

Source Review

Before implementing the real bridge, read docs/SOURCE_REVIEW.md. It records historical package/source behavior that this project needs to preserve or deliberately replace.