Introducing a new way to review your PRs.

Read the announcement

openai / codex

Lightweight coding agent that runs in your terminal

View on GitHub

13 documents · Updated Nov 16, 2026

docs / repo-and-build-system

Repository and Build System

Overview

This area owns the Codex monorepo's repository-level build, test, packaging, and maintenance infrastructure. Route changes here when they affect workspace membership, toolchain pins, Bazel module setup, release packaging, repo-wide scripts, checked-in third-party build inputs, or the shared Rust/Bazel macros that most codex-rs crates consume. Feature code in an individual Rust crate or SDK belongs with that crate, but changes to codex-rs/Cargo.toml, MODULE.bazel, defs.bzl, justfile, scripts/**, bazel/**, tools/**, third_party/**, patches/**, or the root package manager files belong in this doc.

The root package.json is private and is used for repo-wide maintenance rather than for shipping the Rust CLI. It pins Node >=24.22.1, pnpm >=10.34.5, Prettier, security/resolution overrides, and the root scripts for formatting JSON/Markdown/workflows/JS plus regenerating hook schema fixtures through Cargo. pnpm-workspace.yaml declares only three pnpm workspaces (codex-cli, codex-rs/responses-api-proxy/npm, and sdk/typescript) and enables strict dependency/build policy: hoisted linking comes from .npmrc, strictDepBuilds and blockExoticSubdeps are on, and the only allowed package build is the pinned MCP conformance tarball. pnpm-lock.yaml is the lock for those workspaces and mirrors the root overrides. .nvmrc pins local Node to 24.22.1.

The developer entrypoint is justfile. It runs from codex-rs by default while exporting CODEX_REPO_ROOT to the repository root, and its shell is mediated by scripts/just-shell.py so {args} forwarding works on both POSIX shells and PowerShell. Local Cargo recipes include just codex, just exec, just test, just clippy, just bench, schema generation, Windows setup/install, and package assembly. Bazel recipes in the same file run the CLI or code-mode host via bazel run, check/update MODULE.bazel.lock, run bazel test //..., run Bazel-backed Clippy, run the argument-comment lint aspect, and build release archives. scripts/format.py is the implementation behind just fmt/fmt-check; it runs Just formatting, Rust rustfmt from codex-rs, Buildifier via tools/buildifier, Python SDK Ruff, and Ruff for scripts/**.

Bazel is configured at the repository root. .bazelversion pins Bazel 9.2.0; .bazelignore excludes .git and codex-rs/target; .bazelrc sets hermetic toolchain defaults, local caches, runfiles behavior (--noenable_runfiles), workspace status commands, strict action env, remote/CI configs, Clippy and argument-comment-lint configs, Windows cross/native settings, and release-profile settings. BUILD.bazel defines the local Linux/Windows platforms, the Windows GNU/MSVC platform labels used by CI and cross tests, the //:rbe alias, and exports the test launcher templates. rbe.bzl materializes an RBE platform repository whose container digest depends on host CPU architecture and is consumed through MODULE.bazel and //:rbe.

MODULE.bazel is the Bazel module and third-party dependency hub. It registers LLVM, Windows SDK/MSVC, macOS SDK/frameworks, Python/pip toolchains, Rust toolchains, bindgen, prost, foreign_cc, Wine, and remote execution platform repositories. It derives Bazel Rust dependencies from codex-rs/Cargo.toml and codex-rs/Cargo.lock through crate.from_cargo, including supported Linux, macOS, Windows MSVC, and Windows gnullvm triples. It also applies crate annotations and repository overrides for native dependencies such as OpenSSL, zstd, bzip2, zlib, xz, sqlite, aws-lc, V8, GStreamer/voice libraries, jemalloc, curl, ring, mxc-sdk, WebRTC, and patched crates. MODULE.bazel.lock is the lock for this module graph; scripts/check-module-bazel-lock.sh verifies it via Bazel with --lockfile_mode=error, while just bazel-lock-update runs bazel mod deps --lockfile_mode=update.

defs.bzl is the main shared Bazel macro layer for Rust crates. codex_rust_crate wraps rules_rust targets so Bazel mirrors Cargo conventions: it creates package filegroups, optional build scripts, libraries/proc macros, binary targets, unit tests, integration tests, CARGO_BIN_EXE_* bridges, source remapping for Cargo-like paths, Windows stack/link flags, optional Wine-exec test variants, and Windows cross-test wrappers. workspace_root_test in the same file generates test launchers from workspace_root_test_launcher.sh.tpl or .bat.tpl; those launchers resolve runfiles from directory or manifest mode, switch to the codex-rs workspace root when requested, set INSTA_WORKSPACE_ROOT, materialize runfile-backed env vars, apply CODEX_BAZEL_TEST_SKIP_FILTERS, and shard libtest cases with a stable FNV-1a hash. This wrapper exists because the repo disables runfiles symlink trees and because many snapshot tests assume Cargo-like working directories.

codex-rs/Cargo.toml is the Rust workspace manifest. It declares all workspace members, shared package metadata (version 0.0.0, Rust 2024 edition, Apache-2.0), workspace dependencies, workspace lint levels, Cargo profiles (dev, dev-small, release, profiling, ci-test), and [patch] overrides for forked crates such as crossterm, SQLx, tokio-tungstenite/tungstenite, and v8. codex-rs/Cargo.lock is both Cargo's lockfile and the source used by Bazel's crate.from_cargo. codex-rs/…/config.toml keeps Cargo behavior aligned with Bazel for Windows stack size/static CRT, curl NTLM C flags, and jemalloc configuration. codex-rs/BUILD.bazel exports workspace files, defines the runtime_package_build_mode flag, an e2e benchmark suite, and runtime package archive targets that combine the CLI, app-server, code-mode host, exec server, Linux bwrap, and Windows sandbox helpers.

Packaging has two paths that meet at the same runtime layout. The Bazel path uses bazel/rules/runtime_package.bzl; release_binary transitions binaries into the release profile, collects sidecar symbols (.dSYM or .pdb), and exposes release_files plus tar archives, while runtime_archive builds flat staging archives consumed by codex-rs/BUILD.bazel. bazel/platforms/release_binaries.bzl maps release platform names to Rust triples for multiplatform binary groups. The Python path starts at scripts/build_codex_package.py, which dispatches to scripts/…/cli.py: it builds or accepts prebuilt Cargo artifacts, copies the entrypoint, codex-code-mode-host, codex-exec-server, ripgrep, Linux bwrap, and Windows sandbox helpers into bin/, codex-path/, and codex-resources/, writes codex-package.json, optionally strips Unix binaries, validates the layout, and writes .tar.gz, .tgz, .tar.zst, or .zip archives. scripts/…/targets.py defines the supported release triples and package variants, and requires CODEX_REPO_ROOT, which just assemble-codex-package supplies. scripts/stage_npm_packages.py stages npm packages for release by expanding package names, downloading native workflow artifacts from GitHub Actions when requested, and reusing codex-cli/…/build_npm_package.py metadata.

bazel/** contains focused Starlark support around that graph. bazel/build-info/BUILD.bazel isolates STABLE_GIT_COMMIT into a small stamped env file so Rust compiler actions do not depend on volatile workspace status. scripts/workspace-status.sh and .cmd provide that commit value from STABLE_GIT_COMMIT, Git, GITHUB_SHA, or unknown. bazel/rules/schema_bundle.bzl generates app-server schema bundles and Python SDK exports with explicit generator inputs. bazel/rules/e2e_benchmark.bzl wraps Divan benchmark binaries in workspace_root_test. bazel/rules/testing/** provides foreign-platform and Wine testing helpers. bazel/extensions/codex_release_archive.bzl materializes compatibility-test release packages from CODEX_COMPAT_RELEASES JSON. bazel/tools/dsymutil is surfaced so macOS Rust binaries can find the expected tool path inside Bazel actions.

tools/** is for repository-maintenance tools rather than product features. The important owned tool is tools/argument-comment-lint: it is an isolated Dylint/rustc-driver lint crate for enforcing Rust /*param*/ comments on ambiguous literal arguments. The default repo-wide path is Bazel-backed: .bazelrc config argument-comment-lint applies tools/argument-comment-lint/lint_aspect.bzl, and just argument-comment-lint builds the labels from tools/…/list-bazel-targets.sh. The targeted escape hatches are run-prebuilt-linter.py, which resolves the checked-in DotSlash package, and run.py, which builds the lint from source. tools/buildifier is the DotSlash entry used by scripts/format.py for Starlark formatting.

third_party/** and patches/** are checked-in build inputs and patch overlays used by Bazel and packaging. patches/BUILD.bazel exposes module and crate patches referenced from MODULE.bazel; do not treat these as ad hoc source edits because they are part of external repository construction. third_party/v8/** owns the Bazel integration for the v8 crate: it fetches/overlays V8 source and dependencies, defines source and release-pair artifacts, selects archive/binding inputs for the Rust v8 crate, and documents the update flow in third_party/…/README.md. third_party/voice/** owns the pinned GStreamer/native voice source, SDK, and runtime preparation inputs; its README makes clear these targets prepare build/runtime payloads but do not by themselves enable voice in product packages. third_party/sqlite, third_party/openssl, third_party/powershell, third_party/wine, and codex-rs/vendor/** provide Bazel overlays or filegroups for native dependencies such as sqlite, openssl-sys, PowerShell, Wine, and vendored bubblewrap sources.

Coupling

  • If codex-rs/Cargo.toml or codex-rs/Cargo.lock changes dependency resolution, also update and verify Bazel through MODULE.bazel/MODULE.bazel.lock: MODULE.bazel imports the Cargo graph with crate.from_cargo, and many native crates require explicit annotations or patches there.
  • If Windows Rust flags change, keep codex-rs/…/config.toml, defs.bzl, .bazelrc, and the release transitions in bazel/rules/runtime_package.bzl aligned. Cargo and Bazel both encode Windows stack size and MSVC static CRT policy; divergence produces binaries/tests with different runtime behavior.
  • If release profile behavior changes, update both Cargo and Bazel. codex-rs/Cargo.toml defines Cargo release, while .bazelrc and bazel/rules/runtime_package.bzl reproduce release LTO, codegen-units, debug-info, build-script profile, macOS deployment target, and Linux musl linker behavior for Bazel release archives.
  • If test working-directory, runfiles, or sharding behavior changes, update defs.bzl together with workspace_root_test_launcher.sh.tpl and .bat.tpl. The macro and templates jointly own runfile resolution, INSTA_WORKSPACE_ROOT, CARGO_BIN_EXE_* rewriting, skip filters, and stable sharding.
  • If root pnpm dependencies or workspace packages change, update package.json, pnpm-workspace.yaml, pnpm-lock.yaml, and .npmrc together. The workspace policy intentionally allows very few package build scripts, and the hoisted linker settings are part of how the current JS/TS packages install.
  • If packaging layout changes, update both scripts/…/layout.py and codex-rs/BUILD.bazel/bazel/rules/runtime_package.bzl. The Python package builder writes and validates codex-package.json, while Bazel runtime archives provide the signed/staged binary inputs used by release flows.
  • If V8 crate versions or artifacts change, update codex-rs/Cargo.toml, codex-rs/Cargo.lock, MODULE.bazel, and third_party/v8/** together. MODULE.bazel wires RUSTY_V8_ARCHIVE and RUSTY_V8_SRC_BINDING_PATH to third_party/v8 selectors, and the README documents checksum-manifest validation.
  • If the argument-comment lint policy changes, update tools/argument-comment-lint/src/**, tools/argument-comment-lint/lint_aspect.bzl, .bazelrc's argument-comment-lint config, and justfile recipes together. The source-build, prebuilt DotSlash, and Bazel aspect paths are all supported entrypoints.

Risks

  • MODULE.bazel, MODULE.bazel.lock, and scripts/check-module-bazel-lock.sh: dependency or patch changes that do not refresh the Bazel module lock will fail just bazel-lock-check/CI and can leave local Bazel resolution different from committed state.
  • defs.bzl plus workspace_root_test_launcher.sh.tpl and .bat.tpl: changing sharding or runfile resolution can silently drop tests from a shard or break manifest-only platforms, because the wrapper enumerates libtest names itself and bypasses rules_rust's normal sharding wrapper.
  • .bazelrc, defs.bzl, codex-rs/…/config.toml, and bazel/rules/runtime_package.bzl: Windows stack/CRT settings are duplicated for Cargo builds, Bazel tests, and Bazel release binaries. A partial update can produce tests that pass under one build system while release binaries link or run with different Windows runtime assumptions.
  • third_party/v8/**, MODULE.bazel, and codex-rs/Cargo.lock: V8 archives and generated Rust bindings must match the exact v8 crate version and ABI policy. Mixing versions or sandbox/pointer-compression settings breaks consumers at link time or runtime.