ACP adapter for Codex CLI

What it is – @agentclientprotocol/codex-acp is a Node‑JS server that lets an Agent Client Protocol (ACP) client talk to OpenAI Codex. It runs Codex as a subprocess, translates the standard ACP request/response format into Codex API calls, and forwards Codex events back to the client.

Why it matters – ACP is a protocol for building AI‑powered “agents” that can run code, edit files, browse the web, etc. This adapter plugs Codex (the code‑generation model behind GitHub Copilot) into that ecosystem, so developers can use Codex through the same unified interface they use for other agents (ChatGPT, Claude, etc.).

---

Key capabilities

Feature	What it does
Authentication	Supports ChatGPT‑style login, API‑key auth (CODEX_API_KEY / OPENAI_API_KEY), and custom OpenAI‑compatible gateways.
Configurable session	Choose model, reasoning effort, fast mode, sandbox mode, and other Codex settings via environment variables or CODEX_CONFIG.
Rich I/O	Handles text prompts, embedded context, images, resource links, and extra workspace directories.
Tool‑call events	Emits events for shell commands, file changes, permission requests, MCP tool calls, web searches, image generation, token usage, etc.
AIR extensions	Implements the Agent Interaction Runtime (AIR) extensions: diff‑patches, async background tasks, goal tracking, typed warnings/errors, per‑turn file‑change reports, and more.
Sub‑agent sessions	After capability negotiation, creates native sub‑agent sessions with separate histories and permission routing.
Slash commands	Built‑in commands (/status, /mcp, /goal, /review, /compact, /logout, …) for interactive control.
MCP integration	Allows client‑provided MCP servers over stdio or HTTP.
Packaging	Distributed via npm; can be run with npx or installed globally.

---

Quick start (npm)

# Run the latest released version without installing
npx -y @agentclientprotocol/codex-acp

# Or install globally
npm install -g @agentclientprotocol/codex-acp
codex-acp --version

Optional: point the adapter at a different Codex binary:

CODEX_PATH=/my/codex npx -y @agentclientprotocol/codex-acp

For the bleeding‑edge preview builds:

npx -y @agentclientprotocol/codex-acp@preview

---

Runtime configuration (environment variables)

Variable	Purpose
CODEX_API_KEY / OPENAI_API_KEY	API key for Codex authentication (the former takes precedence).
CODEX_PATH	Path to a custom Codex executable.
CODEX_CONFIG	JSON string merged into the Codex session config.
MODEL_PROVIDER	Selects which model provider Codex should use for new sessions.
INITIAL_AGENT_MODE	Sets the initial permission mode (read-only, workspace-write, agent, agent-full-access).
NO_BROWSER	Suppresses the browser‑based ChatGPT login flow.
APP_SERVER_LOGS	Directory where the adapter writes its logs.

---

Development workflow

npm install          # install deps
npm run start        # launch the adapter locally
npm run typecheck    # TypeScript check
npm test             # run test suite
npm run bundle:all   # produce self‑contained binaries in dist/bin

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

---

Extensibility & protocol details

• AIR extensions – The adapter implements the full set of AIR extensions documented in docs/air-extensions.md (diff‑patch, async tasks, goal tracking, session‑failure, etc.). Clients that negotiate these capabilities receive richer, structured events.
• Sub‑agent sessions – Follow the draft ACP sub‑agent RFD; after bilateral negotiation a child session gets its own history and permission routing, falling back to a regular tool‑call if the client does not support it.
• Background terminal tasks – Codex can keep a shell command running after a turn; the adapter surfaces task status and a stop request to AIR‑aware clients.

---

License

Contributions are licensed under the Apache 2.0 license.

---

Bottom line – codex-acp is a production‑ready bridge that lets any ACP‑compatible AI agent use OpenAI Codex with full support for the latest AIR extensions, sub‑agent sessions, and interactive tooling.