Codex ACP (Agent Client Protocol) Agent

An experimental ACP-compatible agent that bridges the OpenAI Codex runtime with ACP clients over stdio. This project is under active development — many features are incomplete or evolving, and breaking changes are likely.

Highlights

• Agent Client Protocol (ACP) over stdio using agent-client-protocol.
• Integrates with the Codex Rust workspace for conversation management and event streaming.
• Slash commands with ACP AvailableCommands updates (advertised to clients on session start).
• Status output tailored for IDEs (workspace, account, model, token usage).
• Discovers custom prompts via Op::ListCustomPrompts and advertises them as commands.

Status: Work in Progress

This repository is a work-in-progress implementation. Some commands are stubs, some behaviors will change, and additional capabilities are planned. Use at your own risk and expect rough edges.

Requirements

• Rust (stable, 1.78+ recommended; the repo uses Rust 2024 edition).
• Network access for building Git dependencies (Codex workspace, ACP crate).

Build

cargo build

Run

The agent communicates over stdin/stdout using ACP JSON-RPC. Launch it and connect from an ACP client (e.g., an IDE integration or a CLI client implementing ACP):

cargo run --quiet

Because this agent speaks on stdio, it is intended to be spawned by your client. For manual testing, you can pipe ACP JSON-RPC messages to stdin and read replies from stdout.

Features

• ACP Agent implementation

  • Handles initialize, authenticate (no-op for now), session/new, session/prompt, session/cancel.
  • Streams Codex events (assistant text and deltas, reasoning deltas, token counts) as session/update notifications.

• Slash Commands (advertised via AvailableCommandsUpdate)

  • Implemented today:
    • /model — Show or set the current model (uses Op::OverrideTurnContext).
    • /approvals — Set approval mode (untrusted | on-request | on-failure | never).
    • /new — Start a new Codex conversation within the same ACP session.
    • /compact — Request conversation compaction (Op::Compact).
    • /status — Rich status (workspace, account, model, token usage).
    • /mcp — List configured MCP tools (Op::ListMcpTools).
  • Stubs or client-driven features (not fully implemented in the agent):
    • /init — Creating AGENTS.md is a client/UX flow; we just inform the user.
    • /diff — Git diff visualization is a TUI/client concern.
    • /mention — Mentions are a client UX feature.

• Available Commands with Custom Prompts

  • On new session the agent first advertises built-in commands.
  • It then requests Op::ListCustomPrompts from Codex and advertises discovered prompts as additional commands (name + path in description). These are discoverable in client popups that read available_commands_update.

Status Output (/status)

The /status command prints a human-friendly summary, e.g.:

📂 Workspace
  • Path: ~/path/to/workspace
  • Approval Mode: on-request
  • Sandbox: workspace-write
  • AGENTS files: (none)

👤 Account
  • Signed in with ChatGPT (or API key / Not signed in)
  • Login: [email protected]
  • Plan: Plus

🧠 Model
  • Name: gpt-5
  • Provider: OpenAI
  • Reasoning Effort: Medium
  • Reasoning Summaries: Auto

📊 Token Usage
  • Session ID: <uuid>
  • Input: 0
  • Output: 0
  • Total: 0

Notes

• Some fields may be unknown depending on your auth mode and environment.
• Token counts are aggregated from Codex EventMsg::TokenCount when available.

Roadmap

• Custom prompt execution as first-class commands (not just discovery/advertising).
• Richer event mapping (tool calls, approvals, patch apply, exec output).
• Persist/restore sessions (session/load).
• Improved /init, /diff, /mention stories for ACP-only environments.
• More slash commands with Op::OverrideTurnContext (e.g., /effort, /summary, /cwd).

Development

• Branching: prefer topic branches; small, focused commits.
• Lint/test locally using cargo check and cargo test where applicable.
• Logging uses env_logger; use RUST_LOG=info during development.

Related Projects

• Zed ACP example (Claude): https://github.com/zed-industries/claude-code-acp
• Agent Client Protocol (Rust): https://crates.io/crates/agent-client-protocol
• OpenAI Codex (Rust workspace): https://github.com/openai/codex

Disclaimer

This project is experimental and actively developed. The surface area and behavior may change. Features shown in the README may not be complete in your current checkout.