seren-acp-codex

ACP (Agent Client Protocol) for OpenAI Codex.

What it is

seren-acp-codex speaks ACP JSON-RPC over stdio and internally:

• Spawns codex app-server as a subprocess
• Translates ACP prompt turns to Codex app-server requests
• Streams Codex events back to the client as ACP session updates
• Bridges Codex approval prompts through ACP session/request_permission
• Uses JSON-RPC 2.0 when talking to codex app-server (requests require "jsonrpc":"2.0", and responses may omit it)

Architecture

┌────────────┐     stdio      ┌──────────────────┐     stdio      ┌──────────────────┐
│ ACP Client │ ─────────────► │ seren-acp-codex  │ ─────────────► │ codex app-server │
│            │ ◄───────────── │                  │ ◄───────────── │ (subprocess)     │
└────────────┘   JSON-RPC     └──────────────────┘   JSON-RPC     └──────────────────┘

Prerequisites

• Install Codex CLI (see the Codex CLI docs: https://developers.openai.com/codex/cli/)
• Authenticate with Codex: codex login
• ACP spec: https://agentclientprotocol.com/

Running

Note: this binary expects an ACP client to drive it over stdin/stdout. Running it directly will wait for JSON-RPC messages.

# Debug build
cargo run --bin seren-acp-codex

# Release build
cargo run --release --bin seren-acp-codex

# Enable logs
RUST_LOG=info cargo run --release --bin seren-acp-codex
RUST_LOG=debug cargo run --release --bin seren-acp-codex

Session modes

Mode ID	Meaning
ask	Ask before running tools (default)
auto	Auto-approve safe operations

Sandbox configuration

seren-acp-codex configures Codex sandbox mode from SEREN_ACP_CODEX_SANDBOX.

• workspace-write (default)
• danger-full-access
• read-only

Example:

SEREN_ACP_CODEX_SANDBOX=danger-full-access cargo run --release --bin seren-acp-codex

ACP support

Methods

• initialize
• authenticate (no-op; Codex CLI handles auth)
• newSession
• prompt
• setSessionMode
• cancel
• loadSession (resumes an existing Codex thread by ID)

High-level event mapping

• ACP session = Codex thread
• ACP tool calls / permission prompts = Codex approvals (command execution / file changes)

Development

• MSRV: Rust 1.85 (see Cargo.toml)
• cargo fmt
• cargo clippy --all-targets -- -D warnings
• cargo test

License

MIT