ACP adapter for Codex CLI

Use OpenAI Codex from Agent Client Protocol clients.

acp-extension-codex 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.
• Without native subagent negotiation, subagent launches remain standard ACP tool calls with provider-neutral lifecycle data in _meta.lody.task; Codex thread details remain available in _meta.codex.
• 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.
• Native ACP session forking through Codex App Server thread/fork.
• Acknowledged steering of an active Codex turn through app-server turn/steer.
• 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 acp-extension-codex

Or install it globally:

npm install -g acp-extension-codex
acp-extension-codex --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 acp-extension-codex

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.

Lody extensions

The initialize response advertises versioned capabilities under agentCapabilities._meta.lody. Methods and payloads come from acp-extension-core; this includes usage and rate-limit reporting, an independent rate-limit query, acknowledged steering, goals, subagent/background-task lifecycle, compaction lifecycle, and history reads. ACP-standard plans, elicitation, session forking, and context-window usage stay on their standard protocol paths.

Usage reporting assigns differences between native root-thread token snapshots to the model selected for the submitted turn. Cache/input/output/reasoning buckets remain disjoint. Each native turn reports its own cumulative totals, tagged with notification-local _meta.codex.usageTurnId; Lody's matching CLI uses a stable per-turn persistence identity so repeated delivery cannot count a turn twice.

Only the preceding native snapshot and current turn are held in memory. There is no sidecar, historical model ledger or session metadata baseline. Native resume snapshots are comparison points, not new usage; when unavailable, the first notification is conservatively skipped. Subagents are not summed into the root, and native resets, reroutes and crash recovery are best effort rather than exact billing. A mid-turn UI selection change applies to the next submitted turn.

The adapter and Lody CLI must be deployed together for turn-scoped usage. Unmarked older adapters keep their existing accounting scope. Old development sidecars and persisted history are neither read nor automatically migrated.

Codex steering uses _lody/session/steer and confirms application with _lody/session/steer_applied. It keeps the active turn's model, mode, and configuration; slash commands cannot be steered.

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, agent, agent-auto-review, 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.

Local project worktrees

The adapter advertises Core worktreeProject: { version: 1 }. Clients can attach _meta.lody.worktreeProject: { version: 1, originProjectPath: "/original/project" } when creating, loading, resuming, or forking a session, while passing the actual worktree path as ACP cwd. This requires the project APIs in the pinned Codex 0.153.4 runtime; older CODEX_PATH overrides may not support them.

The adapter canonicalizes the root, reuses a matching Codex project, or creates one with a root-derived idempotency key shared by concurrent adapter processes. Multiple matching projects are rejected as ambiguous. New sessions and fork children receive the project assignment; resumed/loaded sessions receive it only when unassigned, preserving existing user choices. Already persisted sessions are backfilled when reopened; there is no bulk migration of unrelated history.

Grouping keeps execution, permissions, and worktree cleanup with their existing owners. It does not enable Codex-managed worktree badges or Handoff. Standard session/list.cwd still filters execution directories. ProjectApi.ts contains the narrow experimental native API subset omitted by stable type generation.