Codex ACP

https://github.com/zed-industries/codex-acp
Admin
An ACP adapter for Codex that enables AI-powered coding assistance through ACP-compatible clients...
Tokens:31,618
Snippets:244
Trust Score:9.8
License:Apache-2.0
Update:1 week ago
Show doc for...
Tokens:
Raw
### Thread usage example

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Shows a typical sequence: set mode, get config options, prompt, and shutdown.

```rust
use codex_acp::thread::Thread;

thread.set_mode(SessionModeId::new("auto")).await?;
let options = thread.config_options().await?;
let stop = thread.prompt(PromptRequest::new(session_id, vec!["Hi".into()])).await?;
thread.shutdown().await?;
```

--------------------------------

### Example using spawn_pipe_process

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Example usage of spawn_pipe_process (alias for spawn_process). Spawns /usr/bin/env with arguments, then receives output and exit status. Requires the codex_utils_pty crate.

```rust
use codex_utils_pty::spawn_pipe_process;
use std::collections::HashMap;

let spawned = spawn_pipe_process(
    "/usr/bin/env",
    &["echo".into(), "hi".into()],
    std::env::current_dir()?.as_path(),
    &HashMap::new(),
    &None,
).await?;
let output = spawned.stdout_rx.recv().await;
let exit = spawned.exit_rx.await?;
```

--------------------------------

### Install adapter with @agentclientprotocol/codex-acp

Source: https://github.com/zed-industries/codex-acp/blob/main/README.md

Use the @agentclientprotocol/codex-acp package for new installs, as development has moved to the new Codex App Server.

```text
@agentclientprotocol/codex-acp
```

--------------------------------

### Example usage of run_main

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/lib.md

Shows how to call run_main from a binary, reading the sandbox path from the CODEX_LINUX_SANDBOX_EXE environment variable and parsing CLI overrides.

```rust
use codex_acp::run_main;
use codex_utils_cli::CliConfigOverrides;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let sandbox = std::env::var_os("CODEX_LINUX_SANDBOX_EXE").map(PathBuf::from);
    let cli_overrides = CliConfigOverrides::parse();
    run_main(sandbox, cli_overrides).await
}
```

--------------------------------

### CodexAgent::serve usage example (run_main)

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Example of serving the agent over stdio. Creates an Arc-wrapped agent, then calls serve with ByteStreams wrapping stdout and stdin.

```rust
let agent = Arc::new(CodexAgent::new(config, sandbox).await?);
let stdin = tokio::io::stdin().compat();
let stdout = tokio::io::stdout().compat_write();
agent.serve(ByteStreams::new(stdout, stdin)).await?;
```

--------------------------------

### CodexAgent::new usage example

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Example of constructing a CodexAgent with a default config and no sandbox binary. Uses Config::load_default() and awaits the new constructor.

```rust
use codex_core::config::Config;
use codex_acp::codex_agent::CodexAgent;

let config = Config::load_default().await?;
let agent = CodexAgent::new(config, None).await?;
```

--------------------------------

### Run codex-acp with OPENAI_API_KEY

Source: https://github.com/zed-industries/codex-acp/blob/main/npm/README.md

Starts the adapter as a regular ACP agent using an OpenAI API key. Replace 'sk-...' with your actual key.

```bash
OPENAI_API_KEY=sk-... codex-acp
```

--------------------------------

### CodexAgent::new

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Creates a new CodexAgent, initializing the shared AuthManager, SQLite state database, EnvironmentManager, ThreadStore, installation id, and ThreadManager.

```APIDOC
## CodexAgent::new

### Description
Creates a new `CodexAgent`: initializes the shared `AuthManager`, the SQLite state database (`init_state_db`), an `EnvironmentManager` rooted at the codex home (with an `ExecServerRuntimePaths` derived from the current executable and the optional Linux sandbox binary), a `ThreadStore` (`thread_store_from_config`), an installation id (`resolve_installation_id`), and a `ThreadManager`.

### Method
Constructor (async)

### Signature
```rust
pub async fn new(
    config: Config,
    codex_linux_sandbox_exe: Option<PathBuf>,
) -> std::io::Result<Self>
```

### Parameters
- `config` (Config) - Required - Fully loaded codex configuration (see `configuration.md`)
- `codex_linux_sandbox_exe` (Option<PathBuf>) - Required - Path to the Linux sandbox helper binary passed to `ExecServerRuntimePaths::new`

### Returns
`std::io::Result<Self>` — the constructed agent. Errors are `std::io::Error`s wrapping failures of the environment manager or installation-id resolution.

### Example
```rust
use codex_core::config::Config;
use codex_acp::codex_agent::CodexAgent;

let config = Config::load_default().await?;
let agent = CodexAgent::new(config, None).await?;
```
```

--------------------------------

### new_session handler signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Signature for the `new_session` handler. Calls `check_auth()` first, uses `request.cwd` and `request.mcp_servers` to build a session config, starts a thread via `thread_manager.start_thread`, records the session root, and wraps the result in a `Thread`. Response includes modes and config options.

```rust
async fn new_session(
    &self,
    request: NewSessionRequest,
    cx: ConnectionTo<Client>,
) -> Result<NewSessionResponse, Error>
```

--------------------------------

### initialize

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/endpoints.md

Initializes the agent with protocol version and client capabilities, returning agent capabilities and authentication methods.

```APIDOC
## initialize

### Description
Initializes the agent with protocol version and client capabilities, returning agent capabilities and authentication methods.

### Method
initialize

### Request Fields
- `protocol_version` (ignored; response always says `V1`)
- `client_capabilities` (stored for capability checks)
- `client_info` (ignored)

### Response
- `protocol_version`: `ProtocolVersion::V1`
- `agent_capabilities.prompt_capabilities`: `embedded_context: true`, `image: true`
- `agent_capabilities.mcp_capabilities`: `http: true`
- `agent_capabilities.load_session`: `true`
- `agent_capabilities.auth`: `logout` enabled
- `agent_capabilities.session_capabilities`: `close`, `list`, `resume` enabled
- `agent_info`: `Implementation::new("codex-acp", CARGO_PKG_VERSION).title("Codex")`
- `auth_methods`: `chatgpt` (Agent), `codex-api-key` (EnvVar), `openai-api-key` (EnvVar)

### Notes
When the `NO_BROWSER` environment variable is set, the first method (`chatgpt`) is removed — device-code login does not work in remote SSH projects.

### Source
`src/codex_agent.rs:440-478`
```

--------------------------------

### RawConPty::new

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Creates a new RawConPty instance with the specified number of columns and rows.

```APIDOC
## RawConPty::new

### Description
Creates a new RawConPty instance with the specified number of columns and rows.

### Method
new

### Signature
`new(cols: i16, rows: i16) -> anyhow::Result<Self>`

### Parameters
- **cols** (i16) - Required - The number of columns.
- **rows** (i16) - Required - The number of rows.

### Returns
- **anyhow::Result<Self>** - The new RawConPty instance or an error.
```

--------------------------------

### authenticate handler signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Signature for the `authenticate` handler. Converts `request.method_id` via `CodexAuthMethod::try_from`. Short-circuits to success when already authenticated with a matching method. For `chatgpt`, starts the login server; for `codex-api-key` and `openai-api-key`, reads the corresponding environment variable and fails if not set.

```rust
async fn authenticate(&self, request: AuthenticateRequest) -> Result<AuthenticateResponse, Error>
```

--------------------------------

### PsuedoCon::new

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Creates a new raw ConPTY wrapper with the specified size and input/output file descriptors.

```APIDOC
## PsuedoCon::new

### Description
Creates a new raw ConPTY wrapper with the specified size and input/output file descriptors.

### Method
new

### Signature
`new(size: COORD, input: FileDescriptor, output: FileDescriptor) -> Result<Self, Error>`

### Parameters
- **size** (COORD) - Required - The initial size of the pseudoconsole.
- **input** (FileDescriptor) - Required - The input file descriptor.
- **output** (FileDescriptor) - Required - The output file descriptor.

### Returns
- **Result<Self, Error>** - The new PsuedoCon instance or an error.

### Errors
Errors carry an HRESULT message, e.g., `"failed to create psuedo console: HRESULT {result}"`.
```

--------------------------------

### SpawnedProcess

Source: https://github.com/zed-industries/codex-acp/blob/main/vendor/codex-utils-pty/README.md

Bundles session, stdout_rx, stderr_rx, and exit_rx for a spawned process.

```APIDOC
## SpawnedProcess

### Description
Bundles session, stdout_rx, stderr_rx, and exit_rx for a spawned process.

### Fields
- **session** (ProcessHandle) - Required - Process handle for interaction.
- **stdout_rx** (receiver) - Required - Receiver for stdout chunks.
- **stderr_rx** (receiver) - Required - Receiver for stderr chunks.
- **exit_rx** (oneshot receiver) - Required - Receiver for exit code.

### Example
```rust
let exit_code = spawned.exit_rx.await.unwrap_or(-1);
```
```

--------------------------------

### run_main

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/lib.md

The primary entry point for the codex_acp crate. Sets up tracing, parses CLI config overrides, loads the codex config, applies residency requirements, constructs a CodexAgent, and serves ACP over stdio.

```APIDOC
## run_main

### Description
Sets up a `tracing_subscriber` on stderr (log level from `RUST_LOG`), parses CLI config overrides, loads the codex `Config`, applies the residency requirement, constructs a `CodexAgent`, and serves ACP over stdio.

### Method
async function

### Signature
```rust
pub async fn run_main(
    codex_linux_sandbox_exe: Option<PathBuf>,
    cli_config_overrides: CliConfigOverrides,
) -> std::io::Result<()>
```

### Parameters
- `codex_linux_sandbox_exe` (Option<PathBuf>) - Required - Sandbox helper binary path, also propagated into `ConfigOverrides`.
- `cli_config_overrides` (CliConfigOverrides) - Required - CLI overrides (e.g. parsed from `-c key=value`); `parse_overrides()` is applied first.

### Returns
`std::io::Result<()>`:
- `std::io::ErrorKind::InvalidInput` — failed to parse `-c` overrides (message: `"error parsing -c overrides: {e}"`).
- `std::io::ErrorKind::InvalidData` — failed to load the config (message: `"error loading config: {e}"`).
- `std::io::ErrorKind::Other` — ACP serving terminated with an error (message: `"ACP error: {e}"`).

### Behavior details
1. `tracing_subscriber::fmt().with_writer(std::io::stderr).with_env_filter(EnvFilter::from_default_env()).init()` — log level controlled by the `RUST_LOG` environment variable.
2. `cli_config_overrides.parse_overrides()` → key/value overrides.
3. `Config::load_with_cli_overrides_and_harness_overrides(cli_kv_overrides, ConfigOverrides { codex_linux_sandbox_exe, ..default })` — loads the codex config.
4. `codex_login::default_client::set_default_client_residency_requirement(config.enforce_residency.value())` — makes the HTTP client send the `x-openai-internal-codex-residency` header on all requests.
5. `CodexAgent::new(config, codex_linux_sandbox_exe)`.
6. `agent.serve(ByteStreams::new(stdout, stdin))` over stdio.

### Example
```rust
use codex_acp::run_main;
use codex_utils_cli::CliConfigOverrides;
use std::path::PathBuf;

#[tokio::main]
async fn main() -> std::io::Result<()> {
    let sandbox = std::env::var_os("CODEX_LINUX_SANDBOX_EXE").map(PathBuf::from);
    let cli_overrides = CliConfigOverrides::parse();
    run_main(sandbox, cli_overrides).await
}
```
```

--------------------------------

### RawConPty::into_handles

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Consumes the RawConPty and returns the underlying PsuedoCon and file descriptors.

```APIDOC
## RawConPty::into_handles

### Description
Consumes the RawConPty and returns the underlying PsuedoCon and file descriptors.

### Method
into_handles

### Signature
`into_handles() -> (PsuedoCon, FileDescriptor, FileDescriptor)`

### Returns
- **(PsuedoCon, FileDescriptor, FileDescriptor)** - A tuple containing the PsuedoCon, input file descriptor, and output file descriptor.
```

--------------------------------

### initialize handler signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Signature for the `initialize` handler. Reads `protocol_version` (ignored), `client_capabilities` (stored), and `client_info` (ignored with TODO). Response capabilities are built with `AgentCapabilities::new()` and include prompt, MCP, session, auth, and agent info capabilities.

```rust
async fn initialize(&self, request: InitializeRequest) -> Result<InitializeResponse, Error>
```

--------------------------------

### set_mode method signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Applies an approval preset, updates local config, and trusts the project for auto/full-access modes.

```rust
pub async fn set_mode(&self, mode: SessionModeId) -> Result<(), Error>
```

--------------------------------

### Spawn a PTY process and collect output (Rust)

Source: https://github.com/zed-industries/codex-acp/blob/main/vendor/codex-utils-pty/README.md

Shows how to spawn a bash process under a PTY using spawn_pty_process, send input via the writer sender, combine stdout and stderr receivers, and await the exit code. Requires tokio_test for the async block and anyhow for error handling.

```rust
use std::collections::HashMap;
use std::path::Path;
use codex_utils_pty::combine_output_receivers;
use codex_utils_pty::spawn_pty_process;
use codex_utils_pty::TerminalSize;

# tokio_test::block_on(async {
let env_map: HashMap<String, String> = std::env::vars().collect();
let spawned = spawn_pty_process(
    "bash",
    &["-lc".into(), "echo hello".into()],
    Path::new("."),
    &env_map,
    &None,
    TerminalSize::default(),
).await?;

let writer = spawned.session.writer_sender();
writer.send(b"exit\n".to_vec()).await?;

// Collect output until the process exits.
let mut output_rx = combine_output_receivers(spawned.stdout_rx, spawned.stderr_rx);
let mut collected = Vec::new();
while let Ok(chunk) = output_rx.try_recv() {
    collected.extend_from_slice(&chunk);
}
let exit_code = spawned.exit_rx.await.unwrap_or(-1);
# let _ = (collected, exit_code);
# anyhow::Ok(())
# });
```

--------------------------------

### load method signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Returns a LoadSessionResponse with the session's modes and config options.

```rust
pub async fn load(&self) -> Result<LoadSessionResponse, Error>
```

--------------------------------

### new_session

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/endpoints.md

Creates a new session with the given working directory and MCP servers, returning session ID, modes, and config options.

```APIDOC
## new_session

### Description
Creates a new session with the given working directory and MCP servers, returning session ID, modes, and config options.

### Method
new_session

### Request Fields
- `cwd`
- `mcp_servers`

### Behavior
1. Auth check — `Error::auth_required()` when not authenticated (see `check_auth`, `src/codex_agent.rs:323`).
2. Builds session config from `cwd` + client MCP servers (`build_session_config`; SSE servers skipped, names whitespace-normalized).
3. `thread_manager.start_thread(config)` — on error, `Error::internal_error()`.
4. Wraps in `Thread`; `thread.load()` provides modes + config options.

### Response
`NewSessionResponse::new(session_id).modes(..).config_options(..)`.

### Source
`src/codex_agent.rs:554-605`
```

--------------------------------

### spawn_pipe_process

Source: https://github.com/zed-industries/codex-acp/blob/main/vendor/codex-utils-pty/README.md

Spawns a process using regular pipes (non-TTY). Returns a SpawnedProcess with the same structure as the PTY variant.

```APIDOC
## spawn_pipe_process

### Description
Spawns a process using regular pipes (non-TTY). Returns a SpawnedProcess with the same structure as the PTY variant.

### Function Signature
`spawn_pipe_process(program, args, cwd, env, arg0) -> SpawnedProcess`

### Parameters
- **program** (string) - Required - The executable to run.
- **args** (list of strings) - Required - Command-line arguments.
- **cwd** (Path) - Required - Working directory for the process.
- **env** (map of string to string) - Required - Environment variables.
- **arg0** (optional string) - Optional - Override for argv[0].

### Returns
- **SpawnedProcess** - Contains `session`, `stdout_rx`, `stderr_rx`, and `exit_rx`.

### Example
```rust
use std::collections::HashMap;
use std::path::Path;
use codex_utils_pty::spawn_pipe_process;

let env_map: HashMap<String, String> = std::env::vars().collect();
let spawned = spawn_pipe_process(
    "bash",
    &["-lc".into(), "echo hello".into()],
    Path::new("."),
    &env_map,
    &None,
).await?;
```
```

--------------------------------

### load

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Loads the session's modes and config options, returning a LoadSessionResponse.

```APIDOC
## load

### Description
Computes the session's modes and config options and returns them in a `LoadSessionResponse`.

### Method
`pub async fn load(&self) -> Result<LoadSessionResponse, Error>`

### Parameters
None.

### Returns
- `Result<LoadSessionResponse, Error>` - The session's modes and config options, or an error.

### Example
```rust
let response = thread.load().await?;
```
```

--------------------------------

### run_main function signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/lib.md

The primary entry point of the codex_acp crate. Sets up tracing, parses CLI overrides, loads config, applies residency requirement, constructs a CodexAgent, and serves ACP over stdio.

```rust
pub async fn run_main(
    codex_linux_sandbox_exe: Option<PathBuf>,
    cli_config_overrides: CliConfigOverrides,
) -> std::io::Result<()>
```

--------------------------------

### Run tests for codex-utils-pty (just command)

Source: https://github.com/zed-industries/codex-acp/blob/main/vendor/codex-utils-pty/README.md

Command to run the unit tests for the codex-utils-pty crate with output capture disabled. Tests cover both PTY and pipe backends.

```bash
just test -p codex-utils-pty --no-capture
```

--------------------------------

### conpty_supported

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Checks whether ConPTY is supported on the current Windows build.

```APIDOC
## conpty_supported

### Description
Checks whether ConPTY is supported on the current Windows build.

### Method
conpty_supported

### Signature
`conpty_supported() -> bool`

### Returns
- **bool** - True if ConPTY is supported, false otherwise.
```

--------------------------------

### PsuedoCon::spawn_command

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Spawns a command in the pseudoconsole and returns a WinChild process handle.

```APIDOC
## PsuedoCon::spawn_command

### Description
Spawns a command in the pseudoconsole and returns a WinChild process handle.

### Method
spawn_command

### Signature
`spawn_command(cmd: CommandBuilder) -> anyhow::Result<WinChild>`

### Parameters
- **cmd** (CommandBuilder) - Required - The command to spawn.

### Returns
- **anyhow::Result<WinChild>** - The spawned child process or an error.
```

--------------------------------

### spawn_process

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Spawns an interactive process on a PTY and returns a SpawnedProcess handle.

```APIDOC
## spawn_process

### Description
Spawns an interactive process on a PTY (portable-pty native system on Unix, ConPtySystem on Windows) and returns the split handle.

### Method
async function

### Signature
```rust
pub async fn spawn_process(
    program: &str,
    args: &[String],
    cwd: &Path,
    env: &HashMap<String, String>,
    arg0: &Option<String>,
    size: TerminalSize,
) -> Result<SpawnedProcess>
```

### Parameters
- **program** (string) - Required - The program to execute.
- **args** (array of strings) - Required - Command-line arguments.
- **cwd** (Path) - Required - Working directory for the process.
- **env** (map of string to string) - Required - Environment variables.
- **arg0** (optional string) - Optional - Override for argv[0].
- **size** (TerminalSize) - Required - Initial terminal size.

### Returns
- **Result<SpawnedProcess>** - The spawned process handle.
```

--------------------------------

### config_options method signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Returns a vector of SessionConfigOption, the union of mode, model, and reasoning_effort select options.

```rust
pub async fn config_options(&self) -> Result<Vec<SessionConfigOption>, Error>
```

--------------------------------

### set_mode

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Applies an approval preset and updates the local config, optionally trusting the project for auto/full-access modes.

```APIDOC
## set_mode

### Description
Applies an approval preset (`Op::ThreadSettings` with `approval_policy`, `permission_profile`, and `active_permission_profile`), updates the local config, and trusts the project when the mode is `auto`/`full-access`.

### Method
`pub async fn set_mode(&self, mode: SessionModeId) -> Result<(), Error>`

### Parameters
- `mode` (SessionModeId) - Required - The mode identifier to set.

### Returns
- `Result<(), Error>` - Success or an error.

### Example
```rust
thread.set_mode(SessionModeId::new("auto")).await?;
```
```

--------------------------------

### spawn_pty_process

Source: https://github.com/zed-industries/codex-acp/blob/main/vendor/codex-utils-pty/README.md

Spawns a process under a pseudo-terminal (PTY). Returns a SpawnedProcess containing session, output receivers, and exit receiver.

```APIDOC
## spawn_pty_process

### Description
Spawns a process under a pseudo-terminal (PTY). Returns a SpawnedProcess containing session, output receivers, and exit receiver.

### Function Signature
`spawn_pty_process(program, args, cwd, env, arg0, size) -> SpawnedProcess`

### Parameters
- **program** (string) - Required - The executable to run.
- **args** (list of strings) - Required - Command-line arguments.
- **cwd** (Path) - Required - Working directory for the process.
- **env** (map of string to string) - Required - Environment variables.
- **arg0** (optional string) - Optional - Override for argv[0].
- **size** (TerminalSize) - Required - PTY dimensions in character cells.

### Returns
- **SpawnedProcess** - Contains `session`, `stdout_rx`, `stderr_rx`, and `exit_rx`.

### Example
```rust
use std::collections::HashMap;
use std::path::Path;
use codex_utils_pty::spawn_pty_process;
use codex_utils_pty::TerminalSize;

let env_map: HashMap<String, String> = std::env::vars().collect();
let spawned = spawn_pty_process(
    "bash",
    &["-lc".into(), "echo hello".into()],
    Path::new("."),
    &env_map,
    &None,
    TerminalSize::default(),
).await?;
```
```

--------------------------------

### initialize response capabilities builder

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-agent.md

Builds the response capabilities for the `initialize` handler. Enables embedded context, image, HTTP MCP, session load, logout auth, and agent info with title 'Codex'.

```rust
AgentCapabilities::new()
    .prompt_capabilities(PromptCapabilities::new().embedded_context(true).image(true))
    .mcp_capabilities(McpCapabilities::new().http(true))
    .load_session(true)
    .auth(AgentAuthCapabilities::new().logout(LogoutCapabilities::new()))
```

--------------------------------

### Thread::new

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Spawns the ThreadActor and returns the Thread wrapper. This is the constructor for creating a new Thread instance.

```APIDOC
## Thread::new

### Description
Spawns the ThreadActor (with a SessionClient built from session_id, cx, and client_capabilities) and returns the wrapper.

### Method
Constructor

### Signature
```rust
pub fn new(
    session_id: SessionId,
    thread: Arc<dyn CodexThreadImpl>,
    auth: Arc<AuthManager>,
    models_manager: Arc<dyn ModelsManagerImpl>,
    client_capabilities: Arc<Mutex<ClientCapabilities>>,
    config: Config,
    cx: ConnectionTo<Client>,
) -> Self
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `session_id` | `SessionId` | yes | — | ACP session id (the codex `ThreadId` as a string) |
| `thread` | `Arc<dyn CodexThreadImpl>` | yes | — | Codex thread handle (`CodexThread` implements the trait) |
| `auth` | `Arc<AuthManager>` | yes | — | Codex auth manager (used by `/logout`) |
| `models_manager` | `Arc<dyn ModelsManagerImpl>` | yes | — | Model listing/resolution used for the `model` config option |
| `client_capabilities` | `Arc<Mutex<ClientCapabilities>>` | yes | — | Shared handle to the client's declared capabilities |
| `config` | `Config` | yes | — | The session config (per-session clone) |
| `cx` | `ConnectionTo<Client>` | yes | — | ACP connection back to the client |

### Returns
- `Self` - The Thread wrapper instance.
```

--------------------------------

### Binary entry point main function

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/lib.md

The main function for the codex-acp binary. Uses arg0 dispatch to parse CLI overrides and call run_main with the sandbox executable path.

```rust
fn main() -> Result<()> {
    arg0_dispatch_or_else(|args| async move {
        let cli_config_overrides = CliConfigOverrides::parse();
        codex_acp::run_main(args.codex_linux_sandbox_exe, cli_config_overrides).await?;
        Ok(())
    })
}
```

--------------------------------

### Run codex-acp via npx

Source: https://github.com/zed-industries/codex-acp/blob/main/npm/README.md

Runs the adapter using npx, which fetches and executes the package from npm.

```bash
npx @zed-industries/codex-acp
```

--------------------------------

### ConPtySystem

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Implements the portable_pty::PtySystem trait on Windows, providing a system-level interface for creating PTYs.

```APIDOC
## ConPtySystem

### Description
Implements the `portable_pty::PtySystem` trait on Windows, providing a system-level interface for creating PTYs.

### Method
ConPtySystem

### Signature
`ConPtySystem` implements `portable_pty::PtySystem`
```

--------------------------------

### spawn_process_with_inherited_fds

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Spawns a PTY process with inherited file descriptors, using a manual openpty path on Unix when needed.

```APIDOC
## spawn_process_with_inherited_fds

### Description
Spawns a PTY process with inherited file descriptors. On Unix with non-empty inherited_fds, uses a manual openpty path that resets signal handlers, clears signal mask, calls setsid(), allocates a controlling TTY, and closes non-preserved fds.

### Method
async function

### Signature
```rust
pub async fn spawn_process_with_inherited_fds(
    program: &str,
    args: &[String],
    cwd: &Path,
    env: &HashMap<String, String>,
    arg0: &Option<String>,
    size: TerminalSize,
    inherited_fds: &[i32],
) -> Result<SpawnedProcess>
```

### Parameters
- **program** (string) - Required - The program to execute.
- **args** (array of strings) - Required - Command-line arguments.
- **cwd** (Path) - Required - Working directory.
- **env** (map of string to string) - Required - Environment variables.
- **arg0** (optional string) - Optional - Override for argv[0].
- **size** (TerminalSize) - Required - Initial terminal size.
- **inherited_fds** (array of integers) - Required - File descriptors to inherit.

### Returns
- **Result<SpawnedProcess>** - The spawned process handle.

### Errors
- "missing program for PTY spawn" when program is empty.
- "failed to openpty: ..." on openpty failure.
```

--------------------------------

### prompt method signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Submits a user prompt or slash command and resolves with the final StopReason.

```rust
pub async fn prompt(&self, request: PromptRequest) -> Result<StopReason, Error>
```

--------------------------------

### spawn_process_no_stdin (aliased spawn_pipe_process_no_stdin)

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Spawns a non-interactive process with stdin closed immediately (PipeStdinMode::Null).

```APIDOC
## spawn_process_no_stdin (aliased spawn_pipe_process_no_stdin)

### Description
Spawns a non-interactive process with stdin closed immediately (`PipeStdinMode::Null`).

### Method
async function

### Signature
```rust
pub async fn spawn_process_no_stdin(
    program: &str,
    args: &[String],
    cwd: &Path,
    env: &HashMap<String, String>,
    arg0: &Option<String>,
) -> Result<SpawnedProcess>
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `program` | `&str` | yes | — | Executable path |
| `args` | `&[String]` | yes | — | Command arguments |
| `cwd` | `&Path` | yes | — | Working directory |
| `env` | `&HashMap<String, String>` | yes | — | Full environment (the child env is cleared, then repopulated) |
| `arg0` | `&Option<String>` | yes | `None` | Override for `argv[0]` |

### Returns
`anyhow::Result<SpawnedProcess>`
```

--------------------------------

### conpty_supported

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Checks whether ConPTY is supported on the current platform.

```APIDOC
## conpty_supported

### Description
On Windows, reports whether ConPTY is available (Windows build number >= MIN_CONPTY_BUILD). On other platforms, always returns true.

### Method
function

### Signature
```rust
pub fn conpty_supported() -> bool
```

### Returns
- **bool** - True if ConPTY is supported.
```

--------------------------------

### ProcessHandle methods

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Methods available on the ProcessHandle type for interacting with a spawned process.

```APIDOC
## ProcessHandle

### Description
Handle for driving a spawned process. Fields are private; implements Debug (opaque) and Drop (dropping terminates the child).

### Methods

#### writer_sender

```rust
pub fn writer_sender(&self) -> mpsc::Sender<Vec<u8>>
```

Channel to write raw bytes to child stdin; if stdin is closed returns a disconnected sender.

#### has_exited

```rust
pub fn has_exited(&self) -> bool
```

True if the wait task observed exit.

#### exit_code

```rust
pub fn exit_code(&self) -> Option<i32>
```

Exit code when known.

#### resize

```rust
pub fn resize(&self, size: TerminalSize) -> anyhow::Result<()>
```

Resizes the PTY in character cells. Errors: "process is not attached to a PTY" when neither local handles nor a resizer exist; "failed to lock ..." on mutex poisoning.

#### close_stdin

```rust
pub fn close_stdin(&self)
```

Closes the child stdin channel.

#### request_terminate

```rust
pub fn request_terminate(&self)
```

Kills the child but leaves reader/writer tasks alive for draining.

#### terminate

```rust
pub fn terminate(&self)
```

Kills the child and aborts all helper tasks.

#### Drop

Calls terminate.
```

--------------------------------

### load_session

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/endpoints.md

Loads an existing session by ID, replaying history, and returns modes and config options.

```APIDOC
## load_session

### Description
Loads an existing session by ID, replaying history, and returns modes and config options.

### Method
load_session

### Request Fields
- `session_id`
- `cwd`
- `mcp_servers`

### Behavior
History **is** replayed (`replay_history = true`). The rollout file is located via `find_thread_path_by_id_str`; errors: `internal_error` with the lookup error text, or `resource_not_found(None)` when no thread exists.

### Response
`LoadSessionResponse::new().modes(..).config_options(..)`.

### Source
`src/codex_agent.rs:607-625`, `restore_session` at `:652`
```

--------------------------------

### spawn_from_driver

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Adapts a ProcessDriver into a standard SpawnedProcess, forwarding broadcast output to mpsc receivers and wiring the terminator.

```APIDOC
## spawn_from_driver

### Description
Adapts a driver into a standard `SpawnedProcess`: forwards broadcast output into the mpsc receivers, observes the driver's exit code (defaults to `-1` on channel close), and wires the terminator into the `ProcessHandle`. After the exit code is seen, the reader tasks keep waiting until the driver closes its broadcast sender.

### Function Signature
```rust
pub fn spawn_from_driver(driver: ProcessDriver) -> SpawnedProcess
```

### Parameters
- **driver** (ProcessDriver) - Required - The driver that provides the process wire format.

### Returns
- **SpawnedProcess** - The standard spawned process with session handle, stdout/stderr receivers, and exit code receiver.

```

--------------------------------

### spawn_process (aliased spawn_pipe_process)

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Spawns a non-interactive process with stdin piped, placing the child in its own process group on Unix and killing by group.

```APIDOC
## spawn_process (aliased spawn_pipe_process)

### Description
Spawns a non-interactive process with `tokio::process::Command`, stdin piped. On Unix the child is placed in its own process group (`set_process_group` in `pre_exec`) and killed by group.

### Method
async function

### Signature
```rust
pub async fn spawn_process(
    program: &str,
    args: &[String],
    cwd: &Path,
    env: &HashMap<String, String>,
    arg0: &Option<String>,
) -> Result<SpawnedProcess>
```

### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `program` | `&str` | yes | — | Executable path |
| `args` | `&[String]` | yes | — | Command arguments |
| `cwd` | `&Path` | yes | — | Working directory |
| `env` | `&HashMap<String, String>` | yes | — | Full environment (the child env is cleared, then repopulated) |
| `arg0` | `&Option<String>` | yes | `None` | Override for `argv[0]` |

### Returns
`anyhow::Result<SpawnedProcess>`

### Example
```rust
use codex_utils_pty::spawn_pipe_process;
use std::collections::HashMap;

let spawned = spawn_pipe_process(
    "/usr/bin/env",
    &["echo".into(), "hi".into()],
    std::env::current_dir()?.as_path(),
    &HashMap::new(),
    &None,
).await?;
let output = spawned.stdout_rx.recv().await;
let exit = spawned.exit_rx.await?;
```
```

--------------------------------

### config_options

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Returns the union of available session config options: mode, model, and reasoning effort (when applicable).

```APIDOC
## config_options

### Description
Returns the union of the `mode` select option (only when a current mode is recognized), the `model` select option, and the `reasoning_effort` select option (only when the current preset advertises more than one supported effort).

### Method
`pub async fn config_options(&self) -> Result<Vec<SessionConfigOption>, Error>`

### Parameters
None.

### Returns
- `Result<Vec<SessionConfigOption>, Error>` - A list of available config options.

### Example
```rust
let options = thread.config_options().await?;
```
```

--------------------------------

### spawn_pty_process

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Spawns an interactive process using a PTY. This is a re-export of pty::spawn_process.

```APIDOC
## spawn_pty_process

### Description
Spawns an interactive process using a PTY. This is a re-export of `pty::spawn_process`.

### Method
Function call

### Endpoint
`codex_utils_pty::spawn_pty_process`

### Parameters
No parameters documented.

### Request Example
No request example available.

### Response
#### Success Response
No response fields documented.

#### Response Example
No response example available.
```

--------------------------------

### Thread::new constructor signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Signature for the Thread::new method, which spawns the ThreadActor and returns the wrapper. Takes session ID, thread handle, auth manager, models manager, client capabilities, config, and connection.

```rust
pub fn new(
    session_id: SessionId,
    thread: Arc<dyn CodexThreadImpl>,
    auth: Arc<AuthManager>,
    models_manager: Arc<dyn ModelsManagerImpl>,
    client_capabilities: Arc<Mutex<ClientCapabilities>>,
    config: Config,
    cx: ConnectionTo<Client>,
) -> Self
```

--------------------------------

### Load Codex configuration with CLI and harness overrides

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/configuration.md

Loads the Codex configuration in `run_main` (`src/lib.rs:23`). `cli_config_overrides.parse_overrides()` parses `-c` key/value overrides from the command line and returns `std::io::ErrorKind::InvalidInput` on failure; `Config::load_with_cli_overrides_and_harness_overrides` reads the normal configuration chain (config files in `config.codex_home` plus override flags) and returns `std::io::ErrorKind::InvalidData` on failure.

```rust
let cli_kv_overrides = cli_config_overrides.parse_overrides()?;
let config_overrides = ConfigOverrides {
    codex_linux_sandbox_exe: codex_linux_sandbox_exe.clone(),
    ..ConfigOverrides::default()
};
let config = Config::load_with_cli_overrides_and_harness_overrides(
    cli_kv_overrides, config_overrides
).await?;
```

--------------------------------

### RawConPty::pseudoconsole_handle

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/codex-utils-pty.md

Returns the raw handle to the pseudoconsole.

```APIDOC
## RawConPty::pseudoconsole_handle

### Description
Returns the raw handle to the pseudoconsole.

### Method
pseudoconsole_handle

### Signature
`pseudoconsole_handle() -> RawHandle`

### Returns
- **RawHandle** - The raw handle to the pseudoconsole.
```

--------------------------------

### replay_history method signature

Source: https://github.com/zed-industries/codex-acp/blob/main/_autodocs/api-reference/thread.md

Replays rollout items as ACP SessionUpdate notifications.

```rust
pub async fn replay_history(&self, history: Vec<RolloutItem>) -> Result<(), Error>
```
Tokens:
Raw