ACP adapter for Codex CLI

Use OpenAI Codex from Agent Client Protocol clients.

codex-acp is a stdio ACP agent server. It starts the Codex App Server, translates ACP requests into Codex operations, and maps Codex events back into the client.

Features

• ChatGPT, API key, and client-provided custom gateway authentication.
• Model, reasoning effort, fast mode, approval, and sandbox mode configuration.
• Concrete recommended model and reasoning-effort values through the opt-in AIR recommended config values capability.
• Text prompts, embedded context, images, resource links, and additional workspace directories.
• Shell command, file change, permission request, MCP tool call, terminal output, reasoning, plan, web search, image generation, image view, token usage, and review events.
• Compact file changes through the negotiated AIR diff patch extension.
• For AIR, one tool call shape with each fact in one field, as the tool call contract defines. Other clients keep the earlier fields.
• Native ACP subagent sessions (after capability negotiation) with separate child histories and root-routed permissions; a legacy tool-call fallback otherwise.
• Mid-turn input through the _session/steering extension, with an opt-in host-owned fallback when no turn can accept it.
• Async Codex questions as non-blocking form elicitations, with answers steered into the turn that asked them.
• Background terminal tasks in AIR, with task status and targeted stop support after capability negotiation.
• Session-scoped long-running goals in AIR through the goal extension.
• Typed warnings and errors through the opt-in AIR session failure extension.
• All AIR extensions, capabilities, and _meta keys: AIR extensions.
• A per-turn agent file-change report after capability negotiation.
• Client-provided, session-scoped system prompt append, preserving configured developer instructions.
• Client-provided MCP servers over command-based stdio config and HTTP transport.
• Slash commands: /status, /mcp (with /mcp reconnect), /skills, /goal, /review, /review-branch, /review-commit, /compact, and /logout, as well as configured skills.

Installation

Run the published package directly:

npx -y @agentclientprotocol/codex-acp

Or install it globally:

npm install -g @agentclientprotocol/codex-acp
codex-acp --version

The npm package includes a compatible @openai/codex dependency. Set CODEX_PATH only when you want the adapter to run a different Codex binary:

CODEX_PATH=/path/to/codex npx -y @agentclientprotocol/codex-acp

To try changes that have landed on main but are not released yet, install from the preview channel. Pushes to main trigger preview publishing without waiting for CI or release-please; release commits are excluded, and newer pushes can replace queued previews. See docs/RELEASES.md.

npx -y @agentclientprotocol/codex-acp@preview

Authentication

The adapter advertises ACP auth methods during initialization. Clients can authenticate with:

• ChatGPT login. Set NO_BROWSER=1 to hide this method in remote or browserless environments.
• API key via CODEX_API_KEY or OPENAI_API_KEY.
• A custom OpenAI-compatible gateway, when the client opts in to the gateway auth capability.

Runtime options

• CODEX_API_KEY - API key used when the API-key auth method is selected. Takes precedence over OPENAI_API_KEY.
• OPENAI_API_KEY - fallback API key used when the API-key auth method is selected.
• CODEX_PATH - run a specific Codex executable instead of the bundled package dependency.
• CODEX_CONFIG - JSON object merged into the Codex session config.
• MODEL_PROVIDER - model provider to pass to Codex for new sessions.
• DEFAULT_AUTH_REQUEST - ACP auth request JSON used when Codex requires authentication.
• INITIAL_AGENT_MODE - initial mode id: read-only, workspace-write, agent, or agent-full-access.
• NO_BROWSER - hide browser-based ChatGPT auth when set.
• APP_SERVER_LOGS - directory for adapter logs.

Development

npm install
npm run start
npm run typecheck
npm test

Build standalone binaries in dist/bin with:

npm run bundle:all

See readme-dev.md for local client configuration, binary packaging, and Codex type regeneration.

Subagent sessions

Subagent sessions follow the draft ACP subagent RFD and are enabled only after bilateral capability negotiation during initialize. Without native negotiation, the subagent lifecycle stays an ordinary ACP tool call.

See docs/subagent-sessions.md for the negotiation, lifecycle events, session/load reconstruction, and legacy fallback details.

Background terminal tasks

Codex can keep a shell command running after a turn continues. AIR clients can show this work in the Async Tasks panel and stop one command.

See AIR extensions for the capability, lifecycle events, and stop request.

License

By contributing, you agree that your contributions will be licensed under the Apache 2.0 License.