Development Setup

Relevant source files

• README.md
• codex-rs/Cargo.lock
• codex-rs/Cargo.toml
• codex-rs/README.md
• codex-rs/cli/Cargo.toml
• codex-rs/cli/src/main.rs
• codex-rs/core/Cargo.toml
• codex-rs/core/src/flags.rs
• codex-rs/core/src/lib.rs
• codex-rs/exec/src/lib.rs
• codex-rs/tui/Cargo.toml
• codex-rs/tui/src/lib.rs

Purpose: This page documents the prerequisites, repository structure, and local build commands needed to contribute to Codex. For information about the CI/CD pipeline and automated builds, see CI Pipeline and Release Pipeline. For testing strategies and test harness usage, see Testing Infrastructure.

---

Prerequisites

Rust Toolchain

The Codex CLI is implemented in Rust and requires a recent stable Rust toolchain:

• Minimum Rust version: 1.80+ (enforced by edition = "2024" in workspace)
• Installation: Install via rustup

The repository uses the 2024 edition of Rust, configured at the workspace level in codex-rs/Cargo.toml74 Individual crates inherit this setting unless overridden.

Platform targets: The CI builds for 8 platforms (see rust-ci.yml for the complete matrix), but for local development you only need your native target. Common targets:

• macOS: aarch64-apple-darwin (Apple Silicon), x86_64-apple-darwin
• Linux: x86_64-unknown-linux-gnu, x86_64-unknown-linux-musl
• Windows: x86_64-pc-windows-msvc

Optional toolchain components:

• cargo-nextest for faster test execution
• sccache for build caching (used in CI, optional locally)

Sources: codex-rs/Cargo.toml1-76 README.md1-60 codex-rs/README.md1-102

---

Node.js and pnpm

The repository includes TypeScript packages for the npm distribution wrapper and shell-tool MCP server:

• Minimum Node.js version: 22+ (see package.json21)
• Package manager: pnpm 10.28.0+ (see package.json24)
• Installation:

The workspace uses pnpm workspaces configured in pnpm-workspace.yaml1-13 with four packages:

1. codex-cli - npm distribution wrapper
2. codex-rs/responses-api-proxy/npm - responses API proxy wrapper
3. sdk/typescript - TypeScript SDK (if present)
4. shell-tool-mcp - MCP server for shell tools

Sources: package.json1-26 pnpm-workspace.yaml1-13 codex-cli/package.json1-23

---

Platform-Specific Dependencies

macOS

• Xcode Command Line Tools: Required for compiling native dependencies

• Homebrew (optional): Useful for installing optional tools like cmake

Linux

The Rust workspace depends on OpenSSL for musl targets. For development on glibc-based systems (Ubuntu, Fedora, etc.), install:

Ubuntu/Debian:

Fedora/RHEL:

For musl targets (Alpine, static builds), the workspace uses vendored OpenSSL (see codex-rs/core/Cargo.toml126-131).

Landlock/seccomp dependencies: The seccompiler crate is used for Linux sandboxing. These are handled by Cargo automatically but require kernel support at runtime.

Windows

• Visual Studio Build Tools: Required for MSVC target
  • Install from Visual Studio Downloads
  • Select "Desktop development with C++" workload
• Windows SDK: Included with Visual Studio Build Tools

Sources: codex-rs/core/Cargo.toml116-143 .github/workflows/rust-ci.yml

---

Repository Structure

The Codex repository is organized as a Cargo workspace (Rust) with an embedded pnpm workspace (TypeScript/Node.js):

Workspace configuration:

• Cargo workspace: codex-rs/Cargo.toml1-76 defines 60+ member crates
• pnpm workspace: pnpm-workspace.yaml1-13 defines 4 TypeScript packages
• Shared dependencies: Managed via workspace.dependencies in codex-rs/Cargo.toml77-299
• Unified lints: codex-rs/Cargo.toml300-337 applies clippy rules to all crates

Key crates:

Crate	Purpose	Binary Name
codex-cli	Multitool CLI entry point, dispatches to TUI/Exec/AppServer	codex
codex-tui	Interactive terminal UI via ratatui	codex-tui (standalone)
codex-exec	Headless automation mode	codex-exec (standalone)
codex-core	Session management, model client, tool execution	(library only)
codex-app-server	JSON-RPC 2.0 API for IDE integration	(library only)
codex-protocol	Shared protocol types (Op, Event, Config)	(library only)

Sources: codex-rs/Cargo.toml1-375 pnpm-workspace.yaml1-13 codex-rs/README.md92-102

---

Cloning and Initial Setup

1. Clone the Repository

2. Verify Prerequisites

3. Initialize Submodules (if any)

The repository uses patched forks of crossterm, ratatui, and tungstenite via Git patches in codex-rs/Cargo.toml362-374 These are handled automatically by Cargo; no submodule initialization is needed.

4. Install Node.js Dependencies

This installs dependencies for:

• Root monorepo tooling (Prettier)
• codex-cli (npm wrapper)
• shell-tool-mcp (MCP server)
• responses-api-proxy (proxy wrapper)

Sources: README.md12-44 codex-rs/README.md5-14

---

Building the Rust Workspace

Standard Development Build

From the codex-rs/ directory:

The default build produces:

• target/debug/codex - main CLI binary
• target/debug/codex-tui - standalone TUI binary
• target/debug/codex-exec - standalone exec binary

Build profiles:

• Debug (cargo build): Fast compilation, includes debug symbols
• Release (cargo build --release): Optimized, stripped symbols (see codex-rs/Cargo.toml348-356)
  • Uses LTO (link-time optimization)
  • codegen-units = 1 for maximum optimization
  • strip = "symbols" to minimize binary size
• CI test (cargo build --profile ci-test): Optimized for fast CI runs (see codex-rs/Cargo.toml357-360)

Platform-Specific Build Notes

Linux musl Targets

For static binaries (used in CI), add the musl target and build:

The workspace configures vendored OpenSSL for musl targets automatically (see codex-rs/core/Cargo.toml126-131).

macOS Code Signing (Local Development)

Ad-hoc signing is automatic on macOS. For distribution, the release pipeline uses Apple notarization (see rust-release.yml).

Windows

The default MSVC toolchain works out of the box. The workspace includes Windows-specific dependencies like windows-sys for sandbox support (see codex-rs/core/Cargo.toml133-139).

Dependency Caching

The CI uses sccache for distributed build caching. For local development, you can optionally install it:

Sources: codex-rs/Cargo.toml348-375 codex-rs/core/Cargo.toml1-173 .github/workflows/rust-ci.yml

---

Building TypeScript Packages

Build All Packages

From the repository root:

Individual Package Commands

codex-cli: This package is a thin npm wrapper that downloads platform-specific binaries. It has no build step—binaries are vendored during the release process.

shell-tool-mcp: TypeScript MCP server with build/test scripts:

Configuration in shell-tool-mcp/package.json22-30

Sources: shell-tool-mcp/package.json1-42 codex-cli/package.json1-23 package.json1-26

---

Running Locally

Run the Main CLI

After building, the codex binary is available at:

Run the TUI Directly

Run Exec Mode

Run the App Server

The app server expects JSON-RPC 2.0 messages on stdin (stdio mode) or WebSocket connections (ws mode). For testing, use the debug client:

Sources: codex-rs/cli/src/main.rs1-1093 codex-rs/README.md51-73

---

Verification and Testing

Quick Smoke Test

Verify the build produces a working binary:

Run Unit Tests

Run Integration Tests

Some crates have integration tests in tests/ directories:

For detailed testing strategies, including TestCodex harness and mock servers, see Testing Infrastructure.

Verify TypeScript Packages

Sources: codex-rs/core/Cargo.toml144-169 shell-tool-mcp/package.json22-30

---

Development Workflow Reference

Common Commands

Task	Command
Build all Rust crates	cargo build (from codex-rs/)
Build release binary	cargo build --release
Run tests	cargo test
Run clippy lints	cargo clippy
Format Rust code	cargo fmt
Install locally	cargo install --path cli
Build TypeScript	pnpm --filter <package> run build
Format TypeScript	pnpm run format

Environment Variables

• RUST_LOG: Control tracing output (e.g., RUST_LOG=codex_core=debug,codex_tui=info)
• RUSTC_WRAPPER: Set to sccache for build caching
• CODEX_HOME: Override default config directory (default: ~/.codex)
• CODEX_RS_SSE_FIXTURE: Path to SSE fixture for offline tests (see codex-rs/core/src/flags.rs1-7)

Dependency Management

Adding a Rust dependency:

1. Add to [workspace.dependencies] in codex-rs/Cargo.toml77-299 if shared
2. Add to individual Cargo.toml with { workspace = true }
3. Run cargo update <crate> to update Cargo.lock

Adding a TypeScript dependency:

1. Add to package-specific package.json
2. Run pnpm install from repository root
3. Commit updated pnpm-lock.yaml

Sources: codex-rs/Cargo.toml77-375 pnpm-workspace.yaml1-13 codex-rs/core/src/flags.rs1-7

---

Troubleshooting

Cargo Build Failures

Issue: error: failed to run custom build command for openssl-sys

• Solution: Install OpenSSL development libraries (see Platform-Specific Dependencies)

Issue: error: package collision in the lockfile

• Solution: Delete Cargo.lock and run cargo build to regenerate

pnpm Install Failures

Issue: ERR_PNPM_NO_MATCHING_VERSION

• Solution: Ensure Node.js 22+ and pnpm 10.28.0+ are installed (see package.json engines)

Issue: Lockfile is up to date, resolution step is skipped

• Solution: Use --frozen-lockfile in CI; use pnpm install (without flag) for local development

Runtime Issues

Issue: codex: command not found after cargo build

• Solution: Binary is at codex-rs/target/debug/codex, not in PATH. Use cargo install --path cli to install to ~/.cargo/bin

Issue: Authentication errors when running locally

• Solution: Run ./target/debug/codex login to authenticate with ChatGPT or API key

Sources: codex-rs/core/Cargo.toml126-131 package.json20-24 README.md12-44

---

Next Steps

• Testing: See Testing Infrastructure for test harness usage and integration test patterns
• Code Organization: See Code Organization Patterns for common patterns (session vs turn scoping, Arc wrapping, error handling)
• CI/CD: See CI Pipeline and Release Pipeline for automated build and distribution details