Skip to main content
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"
After making changes, use these workspace helpers: 
just fmt
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:
CratePurpose
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

pnpm build

​
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
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

Ensure all required tools are installed:
# For Rust
cargo install just cargo-nextest cargo-insta

# For TypeScript
corepack enable
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.
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