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.
• Native ACP subagent sessions (after capability negotiation) with separate child histories and root-routed permissions; a legacy tool-call fallback otherwise.
• Background terminal tasks in AIR, with task status and targeted stop support after capability negotiation.
• Session-scoped long-running goals through the provider-neutral goal extension.
• A per-turn agent file-change report after capability negotiation.
• Client-provided MCP servers over command-based stdio config and HTTP transport.
• Slash commands: /status, /mcp, /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 docs/async-tasks.md 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.