Skip to main content
The codex-rs directory is the root of a Cargo workspace containing the complete Rust implementation of Codex CLI.

​
Workspace Members

The workspace includes 60+ crates organized by functionality. All crate names are prefixed with codex-.
Naming Convention: The core folder contains the codex-core crate, tui contains codex-tui, etc.

​
Core Crates

These crates form the foundation of Codex CLI:

​
codex-core

Business Logic Library

The core business logic for Codex, designed as a reusable library crate.Responsibilities:
  • Conversation and turn management
  • Model interaction and streaming responses
  • Tool execution and sandboxing coordination
  • Configuration loading and validation
  • Session state management
Platform Requirements:
  • macOS: Expects /usr/bin/sandbox-exec (Seatbelt)
  • Linux: Expects binary to handle codex-linux-sandbox arg0
  • All: Supports --codex-run-as-apply-patch for virtual apply_patch CLI

​
codex-cli

Multitool CLI

The main CLI multitool that provides all Codex functionality via subcommands.Subcommands:
  • Default (no subcommand) — Launches TUI
  • exec — Headless execution
  • app-server — JSON-RPC server
  • sandbox — Sandbox testing
  • mcp — MCP server management
  • config — Configuration utilities

​
codex-tui

Terminal User Interface

Fullscreen terminal interface built with Ratatui.Features:
  • Real-time conversation rendering
  • Interactive approvals and prompts
  • Diff visualization
  • Keyboard-driven navigation
  • See TUI Architecture for details

​
codex-exec

Headless CLI

Non-interactive CLI for automation and programmatic use.Usage:
codex exec "your prompt here"
codex exec --ephemeral "run without persisting"
Features:
  • Non-interactive execution
  • Output to stdout
  • Ephemeral mode (no session persistence)
  • RUST_LOG support for debugging

​
codex-app-server

JSON-RPC Server

JSON-RPC 2.0 server for IDE integrations (VS Code, etc.).Protocol:
  • Bidirectional JSON-RPC over stdio or WebSocket
  • Thread/Turn/Item primitives
  • Streaming notifications
  • Approval flows
Clients:
  • Official VS Code extension
  • Custom integrations via protocol

​
Sandbox & Security Crates

Platform-specific sandboxing implementations:
Linux sandboxing using Landlock and Bubblewrap.Components:
  • Standalone codex-linux-sandbox executable
  • Library exposing run_main() for arg0 routing
  • Vendored bubblewrap for filesystem isolation
Current Behavior:
  • Legacy: Landlock + mount protections
  • Modern: Bubblewrap pipeline (feature gated)
  • Read-only by default via --ro-bind / /
  • Writable roots with --bind
  • Protected paths (.git, .codex) re-applied as read-only
  • PID namespace isolation via --unshare-pid
  • Network isolation via --unshare-net
  • Managed proxy mode with internal routing bridge
Cross-platform process hardening applied pre-main.Hardening Steps:
  • Disable core dumps
  • Disable ptrace attach (Linux/macOS)
  • Remove dangerous environment variables
    • LD_PRELOAD
    • DYLD_* variables
Usage:
#[ctor::ctor]
fn harden() {
    codex_process_hardening::pre_main_hardening();
}
Execution policy management for trusted commands.Purpose:
  • Allow-lists for approved commands
  • Session-scoped approvals
  • Policy persistence
  • Trust decision tracking

​
Protocol & Communication Crates

codex-protocol

Core protocol types and message definitions.Contents:
  • Agent instructions and prompts
  • System message templates
  • Collaboration modes
  • Personality presets

codex-app-server-protocol

App Server JSON-RPC schema and types.Features:
  • TypeScript generation
  • JSON Schema export
  • Experimental API gating
  • Wire format validation

codex-rmcp-client

Remote MCP (Model Context Protocol) client.Purpose:
  • Connect to MCP servers
  • Tool discovery and invocation
  • Resource access
  • OAuth flows

codex-mcp-server

Codex as an MCP server.Usage:
codex mcp-server
npx @modelcontextprotocol/inspector codex mcp-server

​
Integration Crates

  • codex-lmstudio — LM Studio integration
  • codex-ollama — Ollama integration
  • codex-backend-client — OpenAI backend client
  • codex-responses-api-proxy — Responses API proxy server
  • codex-config — Configuration loading and validation
  • codex-state — Session state management
  • codex-cloud-requirements — Requirements.toml parsing
  • codex-cloud-tasks — Task execution framework
  • codex-login — Authentication flows
  • codex-feedback — Feedback submission
  • codex-hooks — Git hook management
  • codex-skills — Skill discovery and loading
  • codex-secrets — Secret management

​
Utility Crates

The utils/ directory contains shared utilities: 
utils/absolute-path   — Absolute path handling
utils/home-dir        — Home directory detection
utils/cache           — Caching utilities

​
Specialized Crates

  • codex-file-search — File search and indexing
  • codex-apply-patch — Patch application logic
  • codex-ansi-escape — ANSI escape sequence handling
  • codex-shell-command — Shell command parsing
  • codex-shell-escalation — Privilege escalation
  • codex-stdio-to-uds — stdio to Unix domain socket bridge
  • codex-otel — OpenTelemetry integration
  • codex-network-proxy — Network proxy support
  • codex-test-macros — Test utilities
  • app-server-test-client — App server test client
  • debug-client — Debug client for testing

​
Workspace Configuration

The workspace uses shared configuration in codex-rs/Cargo.toml:

​
Edition & Versioning

[workspace.package]
version = "0.0.0"
edition = "2024"
license = "Apache-2.0"

​
Dependency Management

  • All workspace crates share dependency versions
  • Internal crates use path dependencies
  • External dependencies locked in workspace
  • Custom patches for ratatui, crossterm, tungstenite

​
Build Configuration

[profile.release]
lto = "fat"              # Link-time optimization
split-debuginfo = "off"
strip = "symbols"       # Minimal binary size
codegen-units = 1       # Maximum optimization

​
Linting

Workspace enforces strict Clippy lints:
  • expect_used = "deny"
  • unwrap_used = "deny"
  • manual_* patterns denied
  • Format args must be inlined
  • Redundant operations denied

​
Bazel Integration

The workspace supports Bazel builds alongside Cargo:
  • runfiles integration for test resources
  • cargo-bin utility for binary location
  • Platform-specific build configurations
After changing dependencies, run just bazel-lock-update from repo root to refresh MODULE.bazel.lock.

​
Next Steps

TUI Architecture

Deep dive into the Ratatui-based interface

Sandboxing

Platform-specific security implementations