This page documents the development environment setup for the Codex codebase. It covers toolchain requirements, workspace organization, build configuration, development workflows (formatting, linting, fixing), and schema generation. It specifically details the use of the justfile, rust-toolchain.toml, Nix flakes, and devcontainer configurations (including contributor and secure customer profiles).
The Codex project is a Rust-based monorepo that requires a modern Rust toolchain and platform-specific build dependencies.
The workspace is configured to use specific versions of Rust to ensure consistency across development environments. The active toolchain is managed via rustup justfile59-60 The project uses specific components like rustfmt and clippy which are essential for linting and formatting AGENTS.md11-13
| Component | Purpose |
|---|---|
| rustfmt | Standardizes code style across the workspace. Invoked via just fmt justfile44 |
| clippy | Provides advanced linting and suggests idiomatic Rust improvements. Invoked via just clippy justfile54 |
| Cargo Tools | just, rg (ripgrep), and cargo-insta must be installed before running repository instructions AGENTS.md7 |
The build system relies on several native libraries and tools.
| Requirement | Details | Purpose |
|---|---|---|
| Just | Command runner | Standardizes development tasks defined in the root justfile justfile1-191 |
| Nextest | cargo nextest | Optimized test runner used by just test justfile75-86 |
| Bazel | bazel | Used for hermetic builds, release binaries, and custom linting tasks justfile102-113 |
| Python | python3 | Used for formatting scripts and GitHub Action utilities justfile44-45 |
flake.nix to provide a reproducible development shell..devcontainer/) provides standardized environments for contributors and secure customer profiles.Sources: AGENTS.md7-13 justfile1-191 .github/workflows/rust-release.yml83-132
The Codex codebase is organized as a monorepo containing a Cargo workspace for Rust code and SDKs for external integrations.
codex-core: The primary agent engine crate AGENTS.md5codex-tui: Implementing the Terminal User Interface justfile27-28codex-cli: The main entry point package for the CLI .github/workflows/sdk.yml102codex-mcp-server: Implementation of Codex as an MCP server justfile167-168codex-state: Manages the SQLite database and logs justfile198-199The following diagram maps high-level development concepts to the specific code entities that implement or configure them.
Setup and Configuration Mapping
Sources: AGENTS.md1-67 justfile1-191 .github/workflows/sdk.yml102
The project uses just (invoking the justfile in the repository root) to standardize common development tasks.
| Task | Command | Description |
|---|---|---|
| Formatting | just fmt justfile44 | Runs scripts/format.py to format Rust, Python, and Justfiles justfile45 |
| Linting/Fixing | just fix *args justfile51 | Runs cargo clippy --fix. Scoping with -p is preferred AGENTS.md67 |
| Testing | just test *args justfile81 | Runs cargo nextest run with an 8 MiB stack size justfile7-82 |
| Schema Gen | just write-config-schema justfile171 | Updates codex-rs/core/config.schema.json via codex-write-config-schema justfile172 AGENTS.md34 |
| Protocol Schema | just write-app-server-schema justfile175 | Regenerates app-server protocol schema fixtures justfile176 |
| Hooks Schema | just write-hooks-schema justfile179 | Regenerates hooks schema fixtures justfile180 |
| Custom Lint | just argument-comment-lint justfile185 | Runs the Bazel-powered lint for opaque literal arguments justfile187 |
When Rust dependencies are modified:
just bazel-lock-update to refresh MODULE.bazel.lock justfile138-139 AGENTS.md37-38just bazel-lock-check to verify consistency before CI justfile143-148 AGENTS.md38-39Sources: justfile44-191 AGENTS.md34-67
{} in format! macros AGENTS.md6-12collapsible_if and redundant_closure_for_method_calls AGENTS.md11-13/*param_name*/ comments before opaque literals like None, true, false, or numeric literals AGENTS.md15-18Send bounds over #[async_trait] AGENTS.md22-26Developers should follow a specific sequence when finalizing changes to ensure stability and adherence to sandbox constraints.
Development Command Flow
When developing or testing tools, be aware of environment-based sandbox flags:
CODEX_SANDBOX_NETWORK_DISABLED=1: Set automatically when using the shell tool AGENTS.md9CODEX_SANDBOX=seatbelt: Set when spawning processes via /usr/bin/sandbox-exec on macOS AGENTS.md10Sources: AGENTS.md8-68 justfile44-191 AGENTS.md22-26
Refresh this wiki
This wiki was recently refreshed. Please wait 5 days to refresh again.