Development Setup

Set up your development environment for contributing to Codex CLI

This guide covers the prerequisites and steps needed to set up a development environment for Codex CLI.

System Requirements

Ensure your system meets these minimum requirements before proceeding.

Requirement	Details
Operating systems	macOS 12+, Ubuntu 20.04+/Debian 10+, or Windows 11 via WSL2
RAM	4 GB minimum (8 GB recommended)
Git	2.23+ (optional, recommended for built-in PR helpers)

Rust Development Setup

The primary Codex CLI implementation is written in Rust and lives in the codex-rs/ directory.

1. Clone the Repository

   git clone https://github.com/openai/codex.git
   cd codex/codex-rs
   
2. Install Rust Toolchain

   Install Rust and required components:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
   source "$HOME/.cargo/env"
   rustup component add rustfmt
   rustup component add clippy
   
3. Install Helper Tools

   Install workspace helper tools:

   # Required: justfile command runner
   cargo install just
   
   # Optional: nextest for faster test runs
   cargo install --locked cargo-nextest
   
   # Optional: insta for snapshot testing
   cargo install cargo-insta
   
4. Verify Installation

   Build Codex to verify your setup:

   cargo build
   

   If the build succeeds, you’re ready to start developing!

TypeScript Development Setup

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

The legacy TypeScript CLI lives in the codex-cli/ directory.

1. Navigate to CLI Directory

   cd codex/codex-cli
   
2. Enable Corepack

   corepack enable
   
3. Install Dependencies

   pnpm install
   
4. Linux-Only: Download Sandboxing Binaries

   On Linux, download prebuilt sandboxing binaries (requires gh and zstd):

   ./scripts/install_native_deps.sh
   

DotSlash (Optional)

GitHub Releases contain a DotSlash file for the Codex CLI named codex. Using a DotSlash file makes it possible to commit a lightweight reference to source control to ensure all contributors use the same version of an executable, regardless of platform.

Alternative: Nix Flake Development

Using Nix for reproducible builds

Prerequisite: Nix >= 2.4 with flakes enabled (experimental-features = nix-command flakes in ~/.config/nix/nix.conf).

Enter Development Shell

# For Rust implementation
nix develop .#codex-rs

# For TypeScript implementation
nix develop .#codex-cli

This shell includes Node.js (for TypeScript) or Rust toolchain, installs dependencies, builds the CLI, and provides a codex command alias.

Build Directly

# Build Rust implementation
nix build .#codex-rs
./result/bin/codex --help

# Build TypeScript implementation
nix build .#codex-cli
./result/bin/codex --help

Run via Flake App

# Run Rust implementation
nix run .#codex-rs

# Run TypeScript implementation
nix run .#codex-cli

Use with direnv

If you have direnv installed, automatically enter the Nix shell when you cd into the project:

cd codex-rs
echo "use flake ../flake.nix#codex-rs" >> .envrc && direnv allow

cd ../codex-cli
echo "use flake ../flake.nix#codex-cli" >> .envrc && direnv allow

Next Steps

Now that your environment is set up:

Building

Learn how to build the project

Testing

Run tests to verify your setup

Guidelines

Review contribution guidelines

Configuration

Explore configuration options