codex-acp

README

codex-acp

Bring Codex to your ACP-compatible editor or client.

Use your existing Codex login to chat, work with files, and connect tools through Agent Client Protocol. Choose your model and reasoning effort from your client's session controls.

Features

• Single Go binary. About 4 MiB: published v1.9.3 binaries are 3.8–4.2 MiB across platforms (3.9 MiB on Linux x64). The standalone binary needs no Node.js, Python, or shared-library runtime; Codex CLI is required.
• Your Codex account. Sign in with the native Codex login flow.
• Models and reasoning controls. Select available models and supported reasoning effort levels without restarting the agent.
• Resumable sessions. List and resume Codex sessions, keep multiple sessions open, and cancel a running request.
• Images and file references. Send text, images, and local file links from clients that support them.
• Connected tools. Attach MCP servers to a session and handle tool approval requests in clients that support permissions.
• Streaming. Receive reasoning updates and optionally stream response text.

Get started

You need the Codex CLI on PATH, a Codex account with access, and an ACP-compatible client. Install:

npm install -g codex-acp@latest

If you haven't already signed in to Codex:

codex-acp login

Configure your ACP client to launch this command:

codex-acp

If your client has separate command and arguments fields, set command to codex-acp and leave arguments empty. The client starts the agent and provides the chat interface.

Prefer to skip the global install? Configure the client to launch:

npx -y codex-acp@latest

Prefer the standalone binary? Download an archive from Releases, extract it, and put codex-acp (or codex-acp.exe on Windows) on PATH. No npm or Go installation is needed for the standalone binary.

Try it in your terminal

acpchat provides an interactive client:

npx -y @baldaworks/acpchat -- npx -y codex-acp@latest

Platforms

Platform	Architectures
macOS	Apple Silicon (arm64), Intel (x64)
Linux	arm64, x64
Windows	x64

npm selects the native binary for your platform automatically.

Performance

A measured Linux x64 run with 100 idle Codex sessions used 13.2 MiB of RSS for codex-acp, plus 1.1 GiB for the Codex backend process tree. The local test backend completed an ACP prompt round-trip in 0.53 ms; a real Codex prompt took 5.31 s, including model generation.

These are measurements from one machine, not performance guarantees. See benchmarks and methodology for session creation, per-session memory growth, environment details and reproduction commands.

Documentation and support

• Usage and configuration
• Protocol reference
• Go installation and embedding
• Migration from codex-acp-bridge
• Releases
• Report an issue

Originally developed as normahq/codex-acp-bridge. MIT licensed.