Related Pages

Related topics: Tools, Execution, and Sandboxing, Extensibility: Hooks, Skills, Plugins, and Plan Mode, Remote Control, Multi-Agent Collaboration, and the App Server Protocol

Codex Overview and Workspace Architecture

Purpose and Scope

Codex is OpenAI's locally-runnable coding agent, distributed through multiple entry points that share a single underlying implementation. The top-level README.md positions Codex CLI as a coding agent that "runs locally on your computer," and points users toward the IDE extension, the desktop app (codex app), and Codex Web. The same repository also ships official TypeScript and Python SDKs so that third-party applications can embed the agent.

The monorepo contains three top-level surfaces:

• The Rust workspace at codex-rs/, which holds the agent runtime, the CLI binaries, the TUI, the app server, and the desktop packaging glue (codex-rs/README.md).
• The Node-based codex-cli/ package, which is the legacy JavaScript wrapper installed via npm install -g @openai/codex (codex-cli/package.json).
• The first-party SDKs under sdk/typescript/ and sdk/python/, which spawn the codex CLI and exchange JSONL events with it (sdk/typescript/README.md, sdk/python/README.md).

A repo-wide package.json defines maintenance scripts and version-pins shared dependencies (for example, @modelcontextprotocol/sdk at 1.26.0 and minimatch patches), signalling that the monorepo treats SDKs, Node CLI shims, and Rust crates as one coordinated release unit.

High-Level Architecture

The Rust workspace follows a layered design in which the business core is intentionally decoupled from UIs and the wire transport:

flowchart TD
    User --> IDE[IDE Extension / codex app / codex CLI]
    User --> SDK[TypeScript & Python SDKs]
    SDK -->|spawn JSONL| CLI[codex CLI binary]
    IDE --> TUI[codex-tui / app-server]
    TUI --> Core[codex-core: agent loop, tools, approvals]
    Core --> Api[codex-api: Responses + Compact clients]
    Core --> Tools[codex-tools: host tool models & adapters]
    Core --> Sandbox[Sandbox layer: Seatbelt / bwrap / Windows]
    Core --> Otel[codex-otel: telemetry]
    Core --> Config[codex-config: layered TOML loader]
    Api -->|HTTPS| OpenAI[OpenAI / ChatGPT APIs]
    Exec[codex-exec-server] --> Core
    Exec -->|JSON-RPC| Remote[Remote environment registry]

Key boundaries enforced by the workspace:

• codex-core "implements the business logic for Codex … designed to be used by the various Codex UIs written in Rust" (codex-rs/core/README.md). The TUI, the IDE bridge, and the app-server are all consumers of this core.
• codex-protocol "defines the 'types' for the protocol used by Codex CLI, which includes both 'internal types' for communication between codex-core and codex-tui, as well as 'external types' used with codex app-server," and is meant to stay free of business logic (codex-rs/protocol/README.md).
• codex-api "hosts the request/response models and request builders for Responses and Compact APIs" and "owns provider configuration (base URLs, headers, query params), auth header injection, retry tuning, and stream idle settings" (codex-rs/codex-api/README.md). It sits below codex-core and above the generic transport in codex-client.
• codex-tools is the "shared support crate for building, adapting, and executing model-visible tools outside codex-core," holding host-facing models like ToolSpec, ConfiguredToolSpec, and LoadableToolSpec while explicitly *not* pulling Session, TurnContext, or approval flow into itself yet (codex-rs/tools/README.md).

Rust Workspace Structure

The codex-rs/ directory is a Cargo workspace with one business core and many thin adapters. The package builder documented in scripts/codex_package/README.md shows the canonical runtime layout that every Codex package ships:

.
├── codex-package.json
├── bin
│   └── <entrypoint>[.exe]
├── codex-resources
│   ├── bwrap                             # Linux only
│   ├── zsh/bin/zsh                       # supported Unix targets only
│   ├── codex-command-runner.exe          # Windows only
│   └── codex-windows-sandbox-setup.exe   # Windows only
└── codex-path
    └── rg[.exe]

--variant selects the entrypoint; the documented variants are codex and codex-app-server, and the version in codex-package.json is read from [workspace.package].version in codex-rs/Cargo.toml (scripts/codex_package/README.md). On Linux, the default cargo target is musl to match release artifacts; the builder downloads and verifies a Codex-built V8 release pair before source-building entrypoints for Darwin or Linux targets.

Adjacent crates play specialised roles:

• codex-linux-sandbox produces the codex-linux-sandbox standalone executable plus a run_main() lib entry, and prefers the first bwrap on PATH outside the current working directory, falling back to a bundled bwrap from codex-resources and emitting a startup warning (codex-rs/linux-sandbox/README.md). WSL1 is rejected because it cannot create user namespaces.
• codex-exec-server is "a small JSON-RPC server for spawning and controlling subprocesses through codex-utils-pty," exposing a CLI entrypoint, a Rust ExecServerClient, and a shared protocol module on top of the codex-app-server-protocol envelope (codex-rs/exec-server/README.md). Remote mode registers the local exec-server with the environment registry and reconnects to a service-provided rendezvous websocket; the same --remote flow supports CODEX_API_KEY, ChatGPT sign-in, and Agent Identity JWT auth via --use-agent-identity-auth.
• codex-otel wires OpenTelemetry providers, metrics, and trace-context helpers and exposes a session-scoped SessionTelemetry for business events (codex-rs/otel/README.md).
• codex-git-utils provides patch application plus a lightweight baseline API (ensure_git_baseline_repository, reset_git_repository, diff_since_latest_init) used by internal directories that only need git as a resettable diff mechanism (codex-rs/git-utils/README.md).
• codex-chatgpt "pertains to first party ChatGPT APIs and products such as Codex agent" and is maintained primarily by OpenAI employees (codex-rs/chatgpt/README.md).

Configuration, Sandboxing, and Tool Surfaces

Configuration is layered rather than flat. The codex-config loader is the "canonical place to load and describe Codex configuration layers (user config, CLI/session overrides, cloud-managed config, managed config, and MDM-managed preferences) and to produce … an effective merged TOML config, per-key origins metadata … and per-layer versions (stable fingerprints) used for optimistic concurrency / conflict detection" (codex-rs/config/src/loader/README.md). The exported surface is small and uniform: load_config_layers_state, the ConfigLayerStack type, ConfigLayerEntry, ConfigLoadOptions, LoaderOverrides, and a merge_toml_values helper.

The README excerpt for codex-core documents the sandbox support matrix that the rest of the architecture depends on:

Source: codex-rs/core/README.md and codex-rs/linux-sandbox/README.md.

The tool surface is being incrementally split out of codex-core. codex-tools currently owns "aggregate host models such as ToolSpec, ConfiguredToolSpec, LoadableToolSpec, ResponsesApiNamespace, and ResponsesApiNamespaceTool" along with "host adapters such as schema sanitization, MCP/dynamic conversion, code-mode augmentation, and image-detail normalization" and "shared executable-tool contracts such as ToolExecutor, ToolCall, and ToolOutput" (codex-rs/tools/README.md). The migration is explicitly incremental: orchestration stays in codex-core "until the surrounding boundaries are ready."

SDKs and Integration Surfaces

Both first-party SDKs are thin wrappers around the codex CLI. The TypeScript SDK "spawns the CLI and exchanges JSONL events over stdin/stdout" and exposes startThread() and run() / runStreamed() for buffered or streaming event consumption (sdk/typescript/README.md). The package targets Node 18+ and is shipped as an ESM module with a single "." export pointing at ./dist/index.js (sdk/typescript/package.json). The Python SDK follows the same model, reusing existing Codex authentication by default and offering login_chatgpt(), login_chatgpt_device_code(), and login_api_key() helpers (sdk/python/README.md).

Because both SDKs sit on top of the same CLI, the desktop app, the TUI, and the codex app-server all benefit from a single evolution path: the wire-level Responses/Compact clients in codex-api, the JSONL-over-stdio SDK contract, and the JSON-RPC envelope used by codex-exec-server together form the three integration surfaces that downstream consumers can target.

Community Themes

Several high-engagement community requests map directly to architectural seams that the workspace already exposes:

• Remote Development / Remote Control (Issue #10450, Issue #9224) align with the existing codex-exec-server --remote mode and environment-registry rendezvous described in codex-rs/exec-server/README.md.
• Codex desktop app for Linux (Issue #11023) is bounded by the Linux sandbox support matrix and the bwrap fallback path in codex-rs/linux-sandbox/README.md.
• Event Hooks (Issue #2109) and Plan Mode (Issue #2101) are adjacent to the tool and approval surfaces that codex-tools is actively extracting out of codex-core, and to the layered config origin metadata in codex-rs/config/src/loader/README.md that future hook policies would have to participate in.

See Also

• Codex CLI quickstart and installation: top-level README.md.
• Business core and sandbox support matrix: codex-rs/core/README.md.
• TypeScript SDK reference: sdk/typescript/README.md.
• Python SDK reference: sdk/python/README.md.
• Remote exec / environment registry: codex-rs/exec-server/README.md.
• Configuration loader and layering model: codex-rs/config/src/loader/README.md.

Related Pages

Related topics: Codex Overview and Workspace Architecture, Remote Control, Multi-Agent Collaboration, and the App Server Protocol

Tools, Execution, and Sandboxing

Overview

Codex executes model-driven actions through a layered pipeline: tool definitions are adapted into provider-visible shapes, executable tools run inside a sandboxed environment, and the surrounding crate boundaries decide which pieces can be shared across UIs (TUI, IDE extensions, desktop app). The repository splits these concerns across codex-core (orchestration), codex-tools (shared host-side tool models), codex-linux-sandbox (Linux enforcement), and codex-exec-server (subprocess transport). Source: codex-rs/core/README.md and codex-rs/tools/README.md.

The user-facing CLI entrypoint is the codex multitool binary, which dispatches to helper modes such as codex-linux-sandbox via arg0 inspection. Source: codex-rs/linux-sandbox/README.md. The Codex desktop app and IDE integrations reuse the same codex-core business logic, ensuring consistent tool execution semantics across surfaces. Source: codex-rs/core/README.md.

Tool Framework and Adaptation

The codex-tools crate owns host-facing tool models and adapters that no longer need to live in core/src/tools/spec.rs or core/src/client_common.rs. Its current responsibilities include:

• Aggregate host models such as ToolSpec, ConfiguredToolSpec, LoadableToolSpec, ResponsesApiNamespace, and ResponsesApiNamespaceTool.
• Host discovery models for assembling tool sets, including discoverable-tool models and request-plugin-install helpers.
• Host adapters for schema sanitization, MCP/dynamic conversion, code-mode augmentation, and image-detail normalization.
• Shared executable-tool contracts such as ToolExecutor, ToolCall, and ToolOutput.

Source: codex-rs/tools/README.md.

The crate explicitly avoids moving orchestration, Session, TurnContext, approval flow, or runtime execution logic in one step; extraction is incremental. Internal conventions require src/lib.rs to remain exports-only, with business logic in named module files and unit tests in sibling foo_tests.rs wired through #[path = "foo_tests.rs"]. Source: codex-rs/tools/README.md.

Protocol-level types used by these tools are defined in codex-protocol, which keeps both internal (codex-core ↔ codex-tui) and external (codex app-server) types together while intentionally avoiding material business logic. Source: codex-rs/protocol/README.md.

Execution Layer

Codex runs executable tools through codex-exec-server, a small JSON-RPC server for spawning and controlling subprocesses via codex-utils-pty. It exposes a CLI entrypoint (codex exec-server), a Rust client (ExecServerClient), and shared request/response protocol types. Source: codex-rs/exec-server/README.md.

codex-exec-server owns transport, protocol, and filesystem/process handlers; the top-level codex binary owns hidden helper dispatch for sandboxed filesystem operations and codex-linux-sandbox. It re-exports surface types including Environment, EnvironmentManager, LOCAL_ENVIRONMENT_ID, REMOTE_ENVIRONMENT_ID, ExecutorFileSystem, and CopyOptions/ReadDirectoryEntry/RemoveOptions shape types. Source: codex-rs/exec-server/src/lib.rs.

Remote mode registers the local exec-server with an environment registry and reconnects to a service-provided rendezvous websocket. Authentication reuses standard Codex ChatGPT sign-in state (run codex login first when remote registration needs authentication). Containerized callers that receive an Agent Identity JWT in CODEX_ACCESS_TOKEN can opt in via --use-agent-identity-auth; otherwise CODEX_API_KEY is sent as a bearer token. Source: codex-rs/exec-server/README.md.

Git-related tool actions, including patch application, are handled by codex-git-utils, which exposes apply_git_patch and ApplyGitRequest. The crate also offers a lightweight baseline API for directories that use git only as a resettable diff mechanism: ensure_git_baseline_repository, reset_git_repository, and diff_since_latest_init. Source: codex-rs/git-utils/README.md.

Sandboxing by Platform

Sandbox behavior is platform-specific, and the support matrix is documented in codex-core. Source: codex-rs/core/README.md.

Sources: codex-rs/core/README.md, codex-rs/linux-sandbox/README.md, scripts/codex_package/README.md.

On Linux, Codex prefers the first bwrap found on PATH outside the current working directory. If the system bwrap is too old to support --argv0, the helper continues to use system bubblewrap and switches to a no---argv0 compatibility path for the inner re-exec. When bwrap is missing, Codex falls back to the bundled codex-resources/bwrap binary and emits a startup warning; the same warning path fires when bubblewrap cannot create user namespaces. Source: codex-rs/linux-sandbox/README.md.

The codex-linux-sandbox crate produces both a standalone executable (bundled with the Node.js CLI) and a lib crate exposing run_main() so that the codex-exec CLI and the codex multitool can re-exec into the sandbox when their arg0 matches codex-linux-sandbox. Source: codex-rs/linux-sandbox/README.md.

Architecture Flow

flowchart LR
    A[Codex CLI / IDE / Desktop App] --> B[codex-core orchestration]
    B --> C[codex-tools adapters]
    C --> D[Responses API request shapes]
    B --> E[codex-exec-server]
    E -->|local| F[sandboxed subprocess via codex-utils-pty]
    E -->|remote| G[rendezvous websocket + AgentIdentity/CODEX_API_KEY auth]
    F --> H{macOS Seatbelt / Linux bwrap / Windows runner}
    B --> I[codex-git-utils for patch apply]
    J[codex-protocol] -.types.-> B
    J -.types.-> E

Configuration and Common Failure Modes

Sandbox and tool behavior are configured through the layered codex-config loader, which merges user config, CLI/session overrides, cloud-managed config, managed config, and MDM-managed preferences. The loader exposes load_config_layers_state, ConfigLayerStack, ConfigLayerEntry, ConfigLoadOptions, LoaderOverrides, and merge_toml_values. Per-layer versions act as stable fingerprints for optimistic concurrency / conflict detection. Source: codex-rs/config/src/loader/README.md.

Common failure modes and known limitations surfaced by the community include:

• Missing or outdated bwrap on Linux: Codex falls back to a bundled helper and emits a startup warning; users should verify bwrap version when sandboxing appears to no-op. Source: codex-rs/linux-sandbox/README.md.
• WSL1 environments: sandboxed shell commands that would enter the bubblewrap path are rejected because WSL1 cannot create the required user namespaces. Source: codex-rs/linux-sandbox/README.md.
• Remote registration without prior sign-in: codex exec-server --remote requires ChatGPT sign-in via codex login, or containerized callers must supply CODEX_API_KEY or an Agent Identity JWT via CODEX_ACCESS_TOKEN. Source: codex-rs/exec-server/README.md.
• Desktop platform coverage gaps: community reports (issue #11023) highlight macOS desktop performance limitations and demand for a Linux Codex desktop app, which affects which sandbox/runtime path users land on. Source: community context (issue #11023).

See Also

• Codex CLI overview
• codex-core orchestration
• codex-tools shared host crate
• codex-linux-sandbox
• codex-exec-server
• codex-protocol types
• codex-config loader

Related Pages

Related topics: Codex Overview and Workspace Architecture, Remote Control, Multi-Agent Collaboration, and the App Server Protocol

Extensibility: Hooks, Skills, Plugins, and Plan Mode

Overview of Codex Extensibility Surfaces

Codex exposes several extension points that let users and integrators customize agent behavior without modifying the core binary. The repository organizes these surfaces across multiple crates so that extension authors can target a stable contract while codex-core continues to evolve.

The top-level monorepo script write-hooks-schema invokes the codex-hooks crate to materialize schema fixtures, confirming that hooks are a first-class subsystem with a published schema artifact (Source: package.json). Adjacent to this, the codex-tools crate hosts host-visible aggregate tool models (ToolSpec, ConfiguredToolSpec, LoadableToolSpec) and explicitly reserves codex-extension-api for extension-owned executable-tool authoring (Source: codex-rs/tools/README.md). Together these crates define the layering: extensions describe behavior via typed schemas and declarations, while core orchestration stays in codex-core.

Protocol types sit between these layers. The codex-protocol crate defines "internal types" used between codex-core and codex-tui, and "external types" consumed by codex app-server, with the explicit guidance that the crate should hold minimal dependencies and avoid material business logic (Source: codex-rs/protocol/README.md). External integrations such as the TypeScript SDK ride on these typed events rather than scraping logs (Source: sdk/typescript/README.md).

Event Hooks

The hooks subsystem lives in the codex-hooks workspace member. Configuration for hooks is loaded through codex-rs/config/src/hook_config.rs, and the runtime split follows the same pattern as the broader codex codebase: lib.rs is the public surface, engine/mod.rs coordinates dispatch, types.rs holds the wire/event types, declarations.rs describes what users declare, and registry.rs indexes active hook handlers.

The community has asked for pattern-matching hooks that trigger scripts or commands before and after Codex behaviors (Issue #2109: "Event Hooks"). The schema-fixture pipeline in package.json (write-hooks-schema) indicates that hook declarations are intended to be machine-readable so that editors and tooling can validate them before the runtime sees them.

flowchart LR
    Declarations["declarations.rs\nhook declarations"] --> Registry["registry.rs\nactive handlers"]
    Types["types.rs\nevent/payload types"] --> Engine["engine/mod.rs\ndispatch"]
    Registry --> Engine
    Engine --> Core["codex-core\nevent emission"]
    Config["hook_config.rs\nuser TOML config"] --> Registry

Conceptually, a user writes declarative hook entries in their Codex configuration. Those entries are parsed into typed declarations, registered against the runtime, and matched when codex-core emits an event. The engine module orchestrates which handlers fire for which events and routes their output back into the session.

Skills, Plugins, and Custom Tool Authoring

The codex-tools crate is the home for shared support code that does not need to live inside codex-core. Its stated vision is to accumulate "host-visible aggregate tool models," "tool-set planning and discovery helpers," and "MCP and dynamic-tool adaptation into Responses API shapes" over time (Source: codex-rs/tools/README.md). Concretely, the crate today owns ToolSpec, ConfiguredToolSpec, LoadableToolSpec, ResponsesApiNamespace, and ResponsesApiNamespaceTool, plus adapters for schema sanitization and code-mode augmentation.

Skills and plugins today follow a deliberate split:

The migration guidance in the same README warns against pulling Session, TurnContext, or approval flow into codex-tools prematurely. The expected order is: keep extension authoring in codex-extension-api, move host-side planning helpers into codex-tools once they no longer need coupling to codex-core, and only then extract higher-level host infrastructure (Source: codex-rs/tools/README.md).

The TypeScript SDK demonstrates the resulting integration shape: it spawns the codex CLI and exchanges JSONL events over stdin/stdout, with run() and runStreamed() exposing both buffered and incremental turn outputs (Source: sdk/typescript/README.md). Plugin authors building on the same protocol benefit from the same event vocabulary that the official SDK consumes.

Plan Mode and Workflow Control

Plan Mode is the requested workflow where Codex researches and plans before executing any changes, with a way to manage and edit the plan before execution begins (Issue #2101). It is not a separate subsystem in the repository today; instead, the building blocks for it exist in the protocol and tools layers.

codex-protocol exposes typed events that a plan-mode UI can render without scraping internal state, and codex-tools provides the host-side adapters that translate agent output into structured items suitable for review. The crate conventions enforce that lib.rs stays exports-only and that business logic lives in named module files with sibling _tests.rs modules, which keeps plan-related logic isolated and reviewable as it grows (Source: codex-rs/tools/README.md).

For users, the practical path to plan-first behavior today is to invoke Codex in a read-only posture, collect the proposed plan, and then approve execution. Integrators building a richer Plan Mode can use the same codex-protocol events that power the TUI and SDK.

See Also

• Configuration Loading and Layering
• Codex Protocol Types
• Tooling and MCP Integration
• TypeScript SDK

Related Pages

Related topics: Codex Overview and Workspace Architecture, Tools, Execution, and Sandboxing, Extensibility: Hooks, Skills, Plugins, and Plan Mode

Remote Control, Multi-Agent Collaboration, and the App Server Protocol

Overview

Codex exposes a structured JSON-RPC surface that external clients use to drive Codex threads, dispatch tools, and observe agent state. Three pieces of this surface are tightly related:

• The App Server Protocol, defined in codex-app-server-protocol, is the wire envelope and request/response model shared by first-party Codex clients (desktop app, Codex Web, IDE plugins, SDKs). Source: codex-rs/app-server-protocol/src/lib.rs
• The codex-app-server binary implements that protocol. Its entry point wires the message envelope to a MessageProcessor that routes incoming requests to per-feature request processors, including the dedicated remote_control_processor. Source: codex-rs/app-server/src/main.rs, Source: codex-rs/app-server/src/message_processor.rs, Source: codex-rs/app-server/src/request_processors/remote_control_processor.rs
• Remote Control is the subset of the protocol that lets a Codex client on one device drive a Codex CLI running on another device (for example, a phone controlling a desktop).
• Multi-Agent Collaboration is the rollout-trace feature that lets a parent Codex thread spawn child agent threads, dispatch tasks to them, receive their results, and close them out.

These four pieces map directly onto the most active community requests, including "Remote Development in Codex Desktop App" (#10450), "Codex Remote Control" (#9224), and "Codex desktop app for Linux" (#11023). Source: README.md

App Server Protocol

The shared envelope and type definitions live in the codex-app-server-protocol crate. The protocol is consumed both by the long-running codex-app-server process and by smaller embedded servers such as codex-exec-server. As documented, "The server speaks the shared codex-app-server-protocol message envelope on the wire." Source: codex-rs/exec-server/README.md

The MessageProcessor dispatches individual requests to request processors, each owning one feature area. The remote-control processor is one such processor. Source: codex-rs/app-server/src/message_processor.rs, Source: codex-rs/app-server/src/request_processors/remote_control_processor.rs

Wire protocol types are deliberately split between two crates:

• "internal types" for communication between codex-core and codex-tui,
• "external types" exposed to codex app-server.

The protocol crate "should have minimal dependencies" and "should avoid material business logic," with new behavior added via Ext-style traits. Source: codex-rs/protocol/README.md Source: codex-rs/chatgpt/README.md

Transport and request shape

The exec-server README documents the on-the-wire framing used by one consumer of this envelope:

• Local mode speaks JSON-RPC over a websocket at ws://IP:PORT.
• Remote mode is enabled with --remote URL --environment-id ID [--name NAME], which registers the local exec-server with the environment registry and reconnects to the service-provided rendezvous websocket.
• Auth uses standard Codex ChatGPT sign-in state, with CODEX_API_KEY bearer-token support for API-key callers and CODEX_ACCESS_TOKEN (Agent Identity JWT) support for containerized callers via --use-agent-identity-auth.

Source: codex-rs/exec-server/README.md

The same envelope carries codex-app-server request and notification types defined under codex-rs/app-server-protocol/src/protocol/v2/, including dedicated remote-control request and response types. Source: codex-rs/app-server-protocol/src/protocol/v2/remote_control.rs

Remote Control

The Remote Control feature addresses the top community asks: driving the codex CLI on a remote machine from the ChatGPT mobile app's Codex tab (#9224), and bringing the Codex desktop app to remote/SSH workflows (#10450, #11023).

Concretely, Remote Control reuses the exec-server transport. A user starts an exec-server locally:

CODEX_API_KEY="$OPENAI_API_KEY" \
codex exec-server \
  --remote "$REMOTE_REGISTRY_URL" \
  --environment-id "$ENVIRONMENT_ID"

The local binary registers itself with the central environment registry and reconnects to the rendezvous websocket the registry hands back. From that point on, a remote Codex client can dispatch codex-app-server-protocol requests to the local CLI. Source: codex-rs/exec-server/README.md

On the receiving side, the codex-app-server's MessageProcessor routes remote/* requests to a dedicated processor responsible for the remote-control lifecycle: registration, command forwarding, status notifications, and teardown. Source: codex-rs/app-server/src/message_processor.rs, Source: codex-rs/app-server/src/request_processors/remote_control_processor.rs

This design lets the same JSON-RPC surface serve a single-user desktop app, a multi-device remote-control flow, and SDK-driven automation without inventing a second protocol.

Multi-Agent Collaboration

Multi-Agent Collaboration lets one Codex thread spawn and coordinate other Codex threads. The rollout-trace crate documents the v2 model. Source: codex-rs/rollout-trace/README.md

In v2, child threads share the root trace writer: a single root bundle reduces into one graph containing the parent thread, the child threads, and the edges between them. Independent top-level threads still get independent bundles, but a spawned child belongs to its parent's rollout tree, including its raw event log, payload directory, and reduced state.json.

The graph model uses three object types:

• AgentThread — a single thread (parent or child).
• ToolCall — model-visible tool invocations such as spawn_agent, followup_task, send_message, and close_agent.
• ConversationItem — user/assistant messages, including the injected task that triggered a child thread and the assistant result returned from it.

Edges capture information flow: a spawn_agent or followup_task tool call delivers a task into a child thread via an injected ConversationItem; the child's assistant ConversationItem is delivered back to the parent as a subagent notification; and close_agent records the lifecycle end.

flowchart LR
    RootTool["root ToolCall: spawn_agent / followup_task / send_message"]
    ChildInput["child ConversationItem: injected task/message"]
    ChildThread["child AgentThread"]
    ChildResult["child assistant ConversationItem: result message"]
    RootNotice["root ConversationItem: subagent notification"]
    CloseTool["root ToolCall: close_agent"]
    TargetThread["target AgentThread"]

    RootTool -- "spawn/task edge" --> ChildInput
    ChildInput --> ChildThread
    ChildThread --> ChildResult
    ChildResult -- "agent_result edge" --> RootNotice
    CloseTool -- "close_agent edge" --> TargetThread

The reducer enforces strict invariants: raw events replay in seq order, payload files are referenced by stable handles, and lifecycle edges are derived from the raw tool calls rather than inferred heuristically. This guarantees that a parent and its spawned children can be replayed as a single coherent trace. Source: codex-rs/rollout-trace/README.md

SDK and Client Integration

Both first-party SDKs wrap the same on-disk Codex CLI and exchange JSONL events over stdin/stdout, while codex-app-server provides a more structured JSON-RPC surface for richer clients.

Source: sdk/typescript/README.md, Source: sdk/python/README.md, Source: codex-rs/exec-server/README.md

See Also

• Codex CLI overview: README.md
• Codex protocol types: codex-rs/protocol/README.md
• Codex API typed clients: codex-rs/codex-api/README.md
• Rollout trace and multi-agent v2: codex-rs/rollout-trace/README.md
• Linux sandbox: codex-rs/linux-sandbox/README.md
• Related community threads: #10450 (Remote Development in Codex Desktop App), #9224 (Codex Remote Control), #11023 (Codex desktop app for Linux), #2101 (Plan Mode), #2109 (Event Hooks).

Doramagic Pitfall Log

Found 23 structured pitfall item(s), including 2 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/openai/codex/issues/27134

2. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/openai/codex/issues/27384

3. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Codex CLI plugin sync writes bundled plugin marketplace into active workspace
• User impact: Developers may fail before the first successful local run: Codex CLI plugin sync writes bundled plugin marketplace into active workspace
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Codex CLI plugin sync writes bundled plugin marketplace into active workspace. Context: Observed when using node, docker, windows, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/openai/codex/issues/27416

4. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/openai/codex/issues/27416

5. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | github_repo:965415649 | https://github.com/openai/codex

6. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: 0.138.0
• User impact: Upgrade or migration may change expected behavior: 0.138.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: 0.138.0. Context: Observed when using python, windows, macos, linux
• Evidence: failure_mode_cluster:github_release | https://github.com/openai/codex/releases/tag/rust-v0.138.0

7. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Developers should check this configuration risk before relying on the project: 0.139.0
• User impact: Upgrade or migration may change expected behavior: 0.139.0
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: 0.139.0. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_release | https://github.com/openai/codex/releases/tag/rust-v0.139.0

8. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | github_repo:965415649 | https://github.com/openai/codex

9. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Developers should check this migration risk before relying on the project: Unethical business practice
• User impact: Developers may hit a documented source-backed failure mode: Unethical business practice
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Unethical business practice. Context: Observed during version upgrade or migration.
• Evidence: failure_mode_cluster:github_issue | https://github.com/openai/codex/issues/27384

10. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | github_repo:965415649 | https://github.com/openai/codex

11. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | github_repo:965415649 | https://github.com/openai/codex

12. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | github_repo:965415649 | https://github.com/openai/codex

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using codex with real data or production workflows.

• Take approve or not for full access - github / github_issue
• Codex CLI plugin sync writes bundled plugin marketplace into active work - github / github_issue
• Unethical business practice - github / github_issue
• 0.140.0-alpha.2 - github / github_release
• 0.139.0 - github / github_release
• 0.139.0-alpha.3 - github / github_release
• 0.139.0-alpha.2 - github / github_release
• 0.139.0-alpha.1 - github / github_release
• 0.138.0 - github / github_release
• 0.138.0-alpha.8 - github / github_release
• 0.138.0-alpha.7 - github / github_release
• 0.138.0-alpha.6 - github / github_release