Building Codex

Learn how to build Codex CLI from source for Rust and TypeScript implementations

This guide covers building Codex CLI from source, including both the Rust and legacy TypeScript implementations.

Building the Rust Implementation

The Rust implementation is the maintained version of Codex CLI and lives in codex-rs/.

Quick Start

1. Navigate to Workspace

   cd codex/codex-rs
   
2. Build with Cargo

   cargo build
   

   For optimized builds, use cargo build --release

3. Run the TUI

   Launch the TUI with a sample prompt:

   cargo run --bin codex -- "explain this codebase to me"
   

Build-Related Commands

After making changes, use these workspace helpers:

Format code

just fmt

# Scope to specific crate you touched
just fix -p codex-tui

# Or run for all crates (slower)
just fix

# Run after changing ConfigToml or nested config types
just write-config-schema

# Run after changing Rust dependencies
just bazel-lock-update
just bazel-lock-check

Important: Run just fmt automatically after making Rust code changes. Do not re-run tests after running fix or fmt.

Workspace Organization

The codex-rs/ directory is a Cargo workspace with these key crates:

Crate	Purpose
core/	Business logic for Codex - intended as a reusable library crate
tui/	Fullscreen TUI built with Ratatui
exec/	Headless CLI for automation and non-interactive use
cli/	CLI multitool providing TUI and exec via subcommands
app-server/	App server protocol implementation
app-server-protocol/	Protocol types and schemas

For detailed information about each crate, read the module-level README.md files under each crate directory.

Building the TypeScript Implementation

The TypeScript implementation is legacy and has been superseded by the Rust implementation. This section is for reference only.

The legacy TypeScript CLI lives in codex-cli/.

1. Navigate to CLI Directory

   cd codex/codex-cli
   
2. Build with pnpm

   pnpm build
   
3. Run Locally

   # Get usage and options
   node ./dist/cli.js --help
   
   # Run the CLI
   node ./dist/cli.js
   
   # Or link globally
   pnpm link
   

TypeScript Build Commands

Build

pnpm build

pnpm typecheck

pnpm lint

pnpm lint:fix
pnpm format:fix

Debugging

Debugging the Rust CLI

1. Enable Verbose Logging

   Set the RUST_LOG environment variable:

   export RUST_LOG=codex_core=debug,codex_tui=debug
   cargo run --bin codex
   
2. View TUI Logs

   The TUI logs to ~/.codex/log/codex-tui.log by default:

   tail -F ~/.codex/log/codex-tui.log
   

   Override the log directory with:

   cargo run --bin codex -- -c log_dir=./.codex-log
   

RUST_LOG environment variable details

The TUI defaults to RUST_LOG=codex_core=info,codex_tui=info,codex_rmcp_client=info.

Non-interactive mode (codex exec) defaults to RUST_LOG=error with messages printed inline.

See the Rust documentation on RUST_LOG for more configuration options.

Debugging the TypeScript CLI

1. Build with Source Maps

   cd codex-cli
   pnpm run build
   

   This generates cli.js.map alongside cli.js in the dist folder.

2. Run with Debugger

   node --inspect-brk ./dist/cli.js
   

   The program waits until a debugger is attached.

3. Attach Debugger

   Choose one:

   • VS Code: Run Debug: Attach to Node Process from the command palette and select the option with debug port 9229
   • Chrome: Go to chrome://inspect and find localhost:9229, then click inspect

Enable Debug Output

For the TypeScript CLI, enable full API request and response logging:

DEBUG=true codex

Troubleshooting

Build fails with missing dependencies

Ensure all required tools are installed:

# For Rust
cargo install just cargo-nextest cargo-insta

# For TypeScript
corepack enable

Tests fail after building

Make sure you’re running tests from the correct directory:

• Rust: Run from codex-rs/
• TypeScript: Run from codex-cli/

See Testing for detailed test commands.

Format or lint errors

Run the automatic fixers:

# Rust
just fmt
just fix -p <crate>

# TypeScript
pnpm lint:fix
pnpm format:fix

Next Steps

Testing

Learn about testing workflows

Guidelines

Review coding standards