repository·main·Indexed 21 days ago
https://github.com/zed-industries/codex-acpAn Agent Client Protocol (ACP) adapter for Codex (version 0.16.0) that allows interaction with Codex via ACP-compatible clients such as the Zed editor. It supports core capabilities like @-mentions, images, tool calls, and MCP servers, along with slash commands such as /review, /init, and /compact. Authentication is supported via ChatGPT subscriptions, CODEX_API_KEY, or OPENAI_API_KEY. Note: Development has moved to @agentclientprotocol/codex-acp.
Development for this project has moved. For new installations, you should use the new adapter built on the Codex App Server to benefit from pooled implementation and maintenance.
Use the following package for new installs:
@agentclientprotocol/codex-acp
You can use codex-acp as a regular ACP agent with any ACP-compatible client.
Option 1: Binary Installation Download the latest release for your specific architecture and OS from the GitHub releases page.
Option 2: npm (npx)
Run the adapter directly using npx:
npx @zed-industries/codex-acpRunning with API Keys You must provide an API key via environment variables. For example, to use an OpenAI key:
OPENAI_API_KEY=sk-... codex-acpnpx @zed-industries/codex-acpThe latest version of Zed supports this adapter natively. To start a session, open the Agent Panel in Zed and select "New Codex Thread" from the + button menu located in the top-right corner.
For more details on how Zed handles external agents, refer to the External Agent documentation.
When creating or loading a session, you can provide Model Context Protocol (MCP) servers. The CodexAgent supports the following MCP transport types:
command, args, and optional env variables. The agent sets the cwd for the server to match the session's working directory.url and optional headers.Note: Codex replaces any whitespace in MCP server names with underscores (_) to ensure compatibility.
To use Codex as an ACP agent, you must instantiate a CodexAgent with a Config object and then call serve with a transport implementation. The new method handles the setup of authentication managers, thread management, and environment managers.
Note: If you are running in an environment without a browser (e.g., via SSH), the ChatGpt authentication method may be unavailable if the NO_BROWSER environment variable is set.
// Example conceptual usage
let config = Config::default(); // Should be properly configured
let agent = CodexAgent::new(config, None).await?;
let agent_arc = Arc::new(agent);
// Serve the agent over a transport (e.g., stdio or http)
agent_arc.serve(transport).await?;The codex-acp command is provided via a Node.js wrapper that automatically resolves and executes the correct platform-specific binary for your operating system and architecture.
To use the CLI, ensure you have installed the @zed-industries/codex-acp package and its required platform-specific optional dependencies. The wrapper handles the mapping for:
arm64, x64arm64, x64arm64, x64If the underlying binary is missing, the CLI will exit with an error indicating that the optional dependency was not installed.
# Example usage (assuming the package is installed via npm)
# The command passes all arguments directly to the underlying binary
codex-acp --helpThe codex-acp adapter wraps the Codex CLI and provides several capabilities for ACP clients:
@-mentions and images.You can use the following slash commands within the agent interface:
/review (supports optional instructions)/review-branch/review-commit/init/compact/logoutThe adapter supports the following authentication methods:
| Method | Requirements |
|---|---|
| ChatGPT subscription | Requires a paid subscription. Note: This does not work in remote projects. |
CODEX_API_KEY | Set via environment variable. |
OPENAI_API_KEY | Set via environment variable. |
To use an API key, export it to your environment before running the agent.
The CodexAgent provides several methods to manage the lifecycle of agent sessions (threads):
new_session by providing a working directory (cwd) and optional mcp_servers.load_session with a SessionId to resume a previous conversation.resume_session to continue a session, which may replay history if requested.list_sessions to retrieve a paginated list of available sessions, optionally filtered by cwd.close_session to shut down a thread and remove it from active sessions.The run_main function is the primary entrypoint for starting a Codex ACP agent. It initializes the tracing subscriber (logging to stderr), parses configuration overrides, loads the global Config, and sets up the residency requirement for the HTTP client. The agent communicates via stdio, bridging the Agent Client Protocol (ACP) with the codex-rs infrastructure.
To use this function, you must provide an optional path to the codex_linux_sandbox_exe and a CliConfigOverrides object. The agent then serves the protocol using the provided stdin and stdout streams.
use codex_acp::run_main;
use codex_utils_cli::CliConfigOverrides;
use std::path::PathBuf;
#[tokio::main]
async fn main() -> std::io::Result<()> {
let sandbox_exe = Some(PathBuf::from("/path/to/sandbox"));
let cli_overrides = CliConfigOverrides::default(); // Or parsed from CLI
run_main(sandbox_exe, cli_overrides).await
}The CodexAgent allows dynamic adjustment of an active session's behavior:
set_session_mode to change the operational mode of the session via a mode_id.set_session_config_option to update specific configuration parameters (identified by config_id) with a provided value. This returns the updated list of available configuration options.prompt method. This method processes the request against the specific SessionId and returns a PromptResponse containing the stop_reason for the model's generation.