codex-acp-v2

A native Agent Client Protocol v2 agent for the OpenAI Codex app-server. It speaks ACP v2 over stdio, maps each ACP session onto a Codex thread, and translates the Codex thread/*, turn/*, and item/* event surface into ACP session/update frames.

This is an independent project, not an official OpenAI or Agent Client Protocol release. It started from the Apache-2.0 licensed agentclientprotocol/codex-acp and keeps its copyright and license notices. There is no ACP v1 surface and no compatibility layer: everything is written against @agentclientprotocol/sdk/experimental/v2.

What it does

• Session lifecycle: session/new, session/resume (with replayFrom: {type: "start"} transcript replay), session/fork, session/list, session/close, session/delete. Thread visibility follows Codex desktop: session/delete is thread/delete (permanent); hiding is the _codex/session_archive / _codex/session_unarchive extension pair (declared as capabilities._meta.codex.archive), and session/list pages the archive when called with _meta: {codex: {archived: true}}.
• Skills and plugins: _codex/skills_list, _codex/skills_config_write, _codex/plugin_list / _codex/plugin_installed / _codex/plugin_install / _codex/plugin_uninstall / _codex/plugin_read and _codex/marketplace_add / _codex/marketplace_remove / _codex/marketplace_upgrade pass Codex's own request and response shapes through (declared as capabilities._meta.codex.skills / .plugins); _codex/skills_changed tells the client to refetch either catalog.
• Asynchronous prompts: session/prompt returns immediately; the turn is reported through state_update frames (running, requires_action while a permission or form is open, idle with stopReason and token usage). A prompt sent during a running turn is steered into it.
• Streaming: agent_message_chunk / agent_thought_chunk keyed by Codex item id, plan_update (turn plans as items, plan-mode drafts as markdown), usage_update, session_info_update titles, available_commands_update.
• Tool calls as upserts: tool_call_update only. Shell commands stream through ACP terminals (terminal_update, terminal_output_chunk); file changes carry v2 diff content (changes + a git_patch); MCP, dynamic tools, web search, image view/generation, sub-agents, and guardian reviews are all mapped. Context compaction is reported as compaction_update (SDK 1.4), and the user message Codex materializes at turn start is reported as user_message so clients know where it landed in history.
• Permissions: Codex command, file-change, sandbox-permission, and MCP approvals become session/request_permission with a tool_call subject. Every option maps back to the exact Codex decision it came from; anything else fails closed.
• Elicitation: MCP forms and URLs and Codex user-input questions use elicitation/create when the client supports it, with a permission fallback for message-only requests.
• Config options: mode (approval and sandbox preset), model, effort, collaboration_mode (plan mode), and fast_mode when the model offers it.
• Auth: api-key, chat-gpt (browser), and chat-gpt-device-code (URL elicitation).
• Providers: providers/set points Codex's OpenAI slot at any OpenAI-compatible gateway (OpenAI Responses API) without restarting; open sessions are rebound in place.
• Slash commands: /review, /review-branch, /review-commit, /compact, /plan, /status, /mcp, /skills, /logout, plus $skill entries from Codex.

See docs/protocol.md for the exact wire contract.

Requirements

• Codex CLI 0.153.0 or newer — the app-server types under src/app-server are generated from the @openai/codex release named in optionalDependencies, and the agent checks codex --version before starting the server; an older Codex fails at startup with an upgrade hint.
• The Codex executable comes from CODEX_PATH, or from the optional @openai/codex dependency when it is installed. Hosts that ship their own Codex set CODEX_PATH and skip the optional dependency (--omit optional); nothing is downloaded at runtime.

Installation

npx -y @nyssance/codex-acp-v2

or

bun add -g @nyssance/codex-acp-v2
codex-acp-v2 --version

The package bundles a compatible @openai/codex. Set CODEX_PATH to use another Codex executable.

Runtime options

Everything a client needs is negotiated over the wire; environment variables only adjust defaults.

| Variable | Effect | | --- | --- | | CODEX_PATH | Codex executable to spawn (codex app-server). Default: bundled @openai/codex. | | CODEX_CONFIG | JSON object merged into every thread's Codex config. | | MODEL_PROVIDER | Codex model provider for new threads. | | INITIAL_AGENT_MODE | read-only, agent (default), or agent-full-access. | | CODEX_API_KEY / OPENAI_API_KEY | Key used by the api-key auth method. | | NO_BROWSER | Hide the browser-based chat-gpt auth method. | | APP_SERVER_LOGS | Directory for the adapter log file (wire frames included). |

Client configuration

{
  "agent_servers": {
    "Codex": {
      "command": "codex-acp-v2",
      "env": {"CODEX_PATH": "/opt/homebrew/bin/codex"}
    }
  }
}

Development

bun install
bun run typecheck
bun run test          # unit suite with a fake Codex
bun run test:e2e      # live suite against a real codex app-server: prompt, permissions, cancel, resume/fork, gateway
bun run build         # dist/index.js

See readme-dev.md for the architecture.