codex-acp-bridge

Run Codex as an ACP agent.

codex-acp-bridge starts the local codex app-server backend and exposes it to Agent Client Protocol (ACP) clients over stdio. Use it when an ACP runner needs to talk to Codex through a stable command while keeping Codex authentication, session state, model selection, and tool behavior native to the Codex CLI.

It is not an OpenAI API proxy. It uses the authenticated Codex session on the machine where the bridge runs, so no OpenAI API key is required.

Requirements

• codex CLI installed and available in PATH.
• Authenticated Codex session on the host running the bridge.
• Active Codex subscription.

Quickstart

Run the bridge with npx:

npx -y @normahq/codex-acp-bridge@latest

Inspect the ACP handshake:

npx -y @normahq/acp-dump -- npx -y @normahq/codex-acp-bridge@latest

Start an interactive ACP session:

npx -y @normahq/acp-repl -- npx -y @normahq/codex-acp-bridge@latest

Installation

Install globally if your ACP client expects a stable executable name:

npm install -g @normahq/codex-acp-bridge@latest

Then run:

codex-acp-bridge

What The Bridge Provides

• ACP initialize, session/new, session/prompt, session/cancel, and session/resume backed by Codex app-server threads.
• Durable ACP session IDs mapped directly to Codex app-server thread.id values.
• ACP-native model handling through session/new.models and session/set_model.
• ACP session configuration for model-advertised reasoning effort values.
• Text and image prompt blocks.
• Optional streaming for Codex agent messages and reasoning thoughts.
• Per-session MCP server configuration from ACP mcpServers.
• Strict session/new._meta.codex validation for Codex-specific startup options.

For protocol-level details, see docs/usage.md and docs/json-api.md.

Runtime Options

codex-acp-bridge [flags]

Common flags:

• --name: ACP agent name reported in initialize.agentInfo.name. Default: norma-codex-acp-bridge.
• --message-streaming: stream Codex agentMessage deltas as ACP agent_message_chunk updates. Default: false.
• --reasoning-streaming: stream Codex reasoning deltas live. Default: true.
• --reasoning-thoughts: reasoning lane projected as ACP thoughts: off, summary, content, or both. Default: summary.
• --debug: enable debug logging.

Examples:

codex-acp-bridge --name team-codex
codex-acp-bridge --message-streaming
codex-acp-bridge --reasoning-thoughts=both
codex-acp-bridge --reasoning-streaming=false
codex-acp-bridge --debug

Codex Session Metadata

Codex-specific session startup options belong under ACP session/new.params._meta.codex.

Supported keys include:

• sandbox
• approvalPolicy
• approvalsReviewer
• baseInstructions
• developerInstructions
• modelProvider
• personality
• serviceTier
• ephemeral
• profile
• compactPrompt
• config

Unknown keys are rejected with ACP invalid_params. ACP session IDs are generated by the backend; session/new._meta.sessionId is rejected.

Use ACP session/set_model for model changes instead of bridge-specific model flags. Use ACP mcpServers for per-session MCP servers; supported transports are stdio and http, while sse is rejected.

Links

• Repository: https://github.com/normahq/codex-acp-bridge
• Issues: https://github.com/normahq/codex-acp-bridge/issues
• Releases: https://github.com/normahq/codex-acp-bridge/releases
• npm package: https://www.npmjs.com/package/@normahq/codex-acp-bridge