This page documents the Cargo workspace organization of the Codex repository, including workspace member crates, shared dependencies, build configuration, and dependency relationships. For details about the CI/CD build process that consumes this workspace structure, see CI Pipeline. For information about how distribution artifacts are produced from these crates, see Distribution Channels.
The Codex repository is organized as a Cargo workspace with its root manifest at codex-rs/Cargo.toml1-374 The workspace uses Cargo's resolver = "2" for enhanced dependency resolution.
All workspace members inherit common package metadata defined in [workspace.package]:
| Field | Value |
|---|---|
version | "0.0.0" |
edition | "2024" |
license | "Apache-2.0" |
Sources: codex-rs/Cargo.toml68-75
The workspace defines specialized build profiles in addition to the standard dev, release, and test profiles:
Release Profile codex-rs/Cargo.toml347-354:
lto = "fat" - full link-time optimization for maximum performancestrip = "symbols" - removes debug symbols to minimize binary sizecodegen-units = 1 - single codegen unit for better optimizationCI Test Profile codex-rs/Cargo.toml356-359:
debug = 1 - reduced debug symbolsinherits = "test" - based on test profileopt-level = 0 - no optimization for faster compilationThese profiles support the goal of producing zero-dependency native executables distributed via npm, Homebrew, and direct downloads.
Sources: codex-rs/Cargo.toml347-359 codex-rs/README.md1-102
The workspace contains 65 member crates organized into functional categories. The complete list is defined in the [workspace.members] array at codex-rs/Cargo.toml2-65
Sources: codex-rs/Cargo.toml2-65 codex-rs/README.md92-101
The four primary crates that produce user-facing binaries or provide core functionality:
cli - Multitool entry point that dispatches to subcommands codex-rs/cli/Cargo.toml1-65
codexcodex_clicore - Core agent implementation containing session management, model client, tool execution codex-rs/core/Cargo.toml1-170
codex_corecodex-write-config-schema codex-rs/core/Cargo.toml13-14Codex, Session, ModelClient, ThreadManager codex-rs/core/src/lib.rs1-171tui - Interactive terminal UI using ratatui codex-rs/tui/Cargo.toml1-137
codex-tuicodex_tuiCli, run_main, AppExitInfo codex-rs/tui/src/lib.rs1-1000exec - Headless/non-interactive CLI for automation codex-rs/exec/src/lib.rs1-600
codex exec subcommandCli, Command, run_main codex-rs/exec/src/lib.rs13-14Sources: codex-rs/README.md92-101 codex-rs/cli/src/main.rs1-80 codex-rs/core/src/lib.rs1-171 codex-rs/tui/src/lib.rs1-433 codex-rs/exec/src/lib.rs1-100
The utils/ subdirectory contains 22 small utility crates providing focused functionality:
| Utility Crate | Purpose |
|---|---|
utils/absolute-path | AbsolutePathBuf type with validation |
utils/cargo-bin | Locating compiled test binaries |
utils/git | Git repository detection and operations |
utils/cache | Generic caching utilities |
utils/image | Image handling and conversion |
utils/pty | PTY/pseudoterminal management |
utils/cli | CLI parsing helpers (CliConfigOverrides) |
utils/oss | OSS provider bootstrapping |
utils/fuzzy-match | Fuzzy string matching |
utils/sandbox-summary | Sandbox policy descriptions |
| ... | 12 more utility crates |
Sources: codex-rs/Cargo.toml43-63
The workspace defines shared dependencies in [workspace.dependencies] at codex-rs/Cargo.toml77-297 allowing member crates to reference them without specifying versions.
All internal crates are defined with { path = "..." }:
Member crates reference these via workspace = true:
Sources: codex-rs/Cargo.toml78-140 codex-rs/cli/Cargo.toml18-55
Key external dependencies with workspace-wide versions:
| Dependency | Version | Purpose |
|---|---|---|
tokio | 1 | Async runtime |
serde | 1 | Serialization |
serde_json | 1 | JSON parsing |
anyhow | 1 | Error handling |
tracing | 0.1.44 | Logging/observability |
clap | 4 | CLI argument parsing |
ratatui | 0.29.0 | TUI framework |
reqwest | 0.12 | HTTP client |
tokio-tungstenite | 0.28.0 | WebSocket client |
rmcp | 0.15.0 | MCP protocol implementation |
Sources: codex-rs/Cargo.toml142-294
Some dependencies are feature-gated or platform-specific:
Platform-specific codex-rs/core/Cargo.toml113-139:
landlock, seccompiler, keyring[linux-native-async-persistent]core-foundation, keyring[apple-native]keyring[windows-native], windows-sysMusl builds codex-rs/core/Cargo.toml123-128:
openssl-sys[vendored] for static linkingSources: codex-rs/core/Cargo.toml113-139
Sources: codex-rs/cli/Cargo.toml18-55 codex-rs/tui/Cargo.toml24-105 codex-rs/core/Cargo.toml19-111
The dependency graph follows a layered architecture:
protocol, config, utils/* - Type definitions and utilitiescodex-client, codex-api, rmcp-client - External API communicationcore - Session management, model interaction, tool executiontui, exec, app-server - User-facing interfacescli - Multitool dispatcherTest harness crates provide shared test utilities:
app_test_support codex-rs/Cargo.toml79 - Located at app-server/tests/commoncore_test_support codex-rs/Cargo.toml138 - Located at core/tests/commonexec_server_test_support codex-rs/Cargo.toml139 - Located at exec-server/tests/commonmcp_test_support codex-rs/Cargo.toml140 - Located at mcp-server/tests/commonThese are not workspace members but referenced via { path = "..." } in dev-dependencies.
Sources: codex-rs/Cargo.toml79-140
The workspace defines shared Clippy lints in [workspace.lints.clippy] at codex-rs/Cargo.toml302-336 All lints are set to "deny" level, enforcing strict code quality:
Manual operation lints - Deny unnecessary manual implementations:
manual_clamp, manual_filter, manual_find, manual_flatten, manual_map, etc.Efficiency lints - Deny unnecessary copies/clones:
redundant_clone, unnecessary_to_owned, needless_collect, etc.Clarity lints - Deny confusing patterns:
needless_borrow, needless_question_mark, uninlined_format_args, etc.Safety lints - Prevent dangerous operations:
expect_used, unwrap_used - Forces explicit error handlingMember crates inherit these lints via:
Sources: codex-rs/Cargo.toml299-336 codex-rs/core/Cargo.toml16-17
The workspace produces multiple binary artifacts:
codexCrate: cli codex-rs/cli/Cargo.toml8-9
Entry Point: codex-rs/cli/src/main.rs1-800
Purpose: Multitool dispatcher that routes to subcommands
The codex binary analyzes its arguments and either:
exec mode via codex exec codex-rs/cli/src/main.rs85app-server via codex app-server codex-rs/cli/src/main.rs103codex mcp-server codex-rs/cli/src/main.rs100codex-tuiCrate: tui codex-rs/tui/Cargo.toml8-9
Entry Point: codex-rs/tui/src/main.rs (referenced but not shown in excerpts)
Purpose: Standalone TUI launcher (can be invoked directly without cli)
codex-write-config-schemaCrate: core codex-rs/core/Cargo.toml13-14
Purpose: Generates JSON schema for config.toml validation
Sources: codex-rs/cli/Cargo.toml8-9 codex-rs/cli/src/main.rs55-146 codex-rs/tui/Cargo.toml8-9 codex-rs/core/Cargo.toml13-14
The workspace uses [patch.crates-io] to override specific dependencies with forked versions at codex-rs/Cargo.toml361-373:
These patches:
crosstermratatui for TUI enhancementsSources: codex-rs/Cargo.toml361-373
The workspace configuration includes metadata for cargo-shear tool to suppress false positive unused dependency warnings at codex-rs/Cargo.toml339-345:
These dependencies are platform-specific or conditionally used in ways cargo-shear cannot detect automatically.
Sources: codex-rs/Cargo.toml337-345
Refresh this wiki