SpineCodex AGENTS.md

Rust/codex-rs

In the codex-rs folder where the rust code lives:

• Crate names are prefixed with codex-. For example, the core folder's crate is named codex-core
• When using format! and you can inline variables into {}, always do that.
• Install any commands the repo relies on (for example just, rg, or cargo-insta) if they aren't already available before running instructions here.
• Never add or modify any code related to CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR or CODEX_SANDBOX_ENV_VAR.
  • You operate in a sandbox where CODEX_SANDBOX_NETWORK_DISABLED=1 will be set whenever you use the shell tool. Any existing code that uses CODEX_SANDBOX_NETWORK_DISABLED_ENV_VAR was authored with this fact in mind. It is often used to early exit out of tests that the author knew you would not be able to run given your sandbox limitations.
  • Similarly, when you spawn a process using Seatbelt (/usr/bin/sandbox-exec), CODEX_SANDBOX=seatbelt will be set on the child process. Integration tests that want to run Seatbelt themselves cannot be run under Seatbelt, so checks for CODEX_SANDBOX=seatbelt are also often used to early exit out of tests, as appropriate.
• Always collapse if statements per https://rust-lang.github.io/rust-clippy/master/index.html#collapsible_if
• Always inline format! args when possible per https://rust-lang.github.io/rust-clippy/master/index.html#uninlined_format_args
• Use method references over closures when possible per https://rust-lang.github.io/rust-clippy/master/index.html#redundant_closure_for_method_calls
• Avoid bool or ambiguous Option parameters that force callers to write hard-to-read code such as foo(false) or bar(None). Prefer enums, named methods, newtypes, or other idiomatic Rust API shapes when they keep the callsite self-documenting.
• When you cannot make that API change and still need a small positional-literal callsite in Rust, follow the argument_comment_lint convention:
  • Use an exact /*param_name*/ comment before opaque literal arguments such as None, booleans, and numeric literals when passing them by position.
  • A method's sole non-self argument is exempt when the method and parameter names match, such as .enabled(false) for fn enabled(&self, enabled: bool).
  • Do not add these comments for string or char literals unless the comment adds real clarity; those literals are intentionally exempt from the lint.
  • The parameter name in the comment must exactly match the callee signature.
  • You can run just argument-comment-lint to run the lint check locally. This is powered by Bazel, so running it the first time can be slow if Bazel is not warmed up, though incremental invocations should take <15s. Most of the time, it is best to update the PR and let CI take responsibility for checking this (or run it asynchronously in the background after submitting the PR). Note CI checks all three platforms, which the local run does not.
• When possible, make match statements exhaustive and avoid wildcard arms.
• Newly added traits should include doc comments that explain their role and how implementations are expected to use them.
• Discourage both #[async_trait] and #[allow(async_fn_in_trait)] in Rust traits.
  • Prefer native RPITIT trait methods with explicit Send bounds on the returned future, as in 3c7f013f9735 / #16630.
  • Preferred trait shape: fn foo(&self, ...) -> impl std::future::Future<Output = T> + Send;
  • Implementations may still use async fn foo(&self, ...) -> T when they satisfy that contract.
  • Do not use #[allow(async_fn_in_trait)] as a shortcut around spelling the future contract explicitly.
• When writing tests, prefer comparing the equality of entire objects over fields one by one.
• Do not add tests for values that are statically defined.
• Do not add negative tests for logic that was removed.
• Do not add general product or user-facing documentation to the docs/ folder. The official Codex documentation lives elsewhere. The exception is app-server API documentation, which is covered by the app-server guidance below.
• Prefer private modules and explicitly exported public crate API.
• If you change ConfigToml or nested config types, run just write-config-schema to update codex-rs/core/config.schema.json.
• When working with MCP tool calls, prefer using codex-rs/codex-mcp/src/mcp_connection_manager.rs to handle mutation of tools and tool calls. Aim to minimize the footprint of changes and leverage existing abstractions rather than plumbing code through multiple levels of function calls.
• Do not call reset_client_session unnecessarily; let the incremental check logic decide whether to reuse the previous request.
• If you change Rust dependencies (Cargo.toml or Cargo.lock), run just bazel-lock-update from the repo root to refresh MODULE.bazel.lock, and include that lockfile update in the same change. CI verifies lockfile drift.
• Bazel does not automatically make source-tree files available to compile-time Rust file access. If you add include_str!, include_bytes!, sqlx::migrate!, or similar build-time file or directory reads, update the crate's BUILD.bazel (compile_data, build_script_data, or test data) or Bazel may fail even when Cargo passes.
• Do not create small helper methods that are referenced only once.
• For tracing async work, instrument the function or method definition with #[tracing::instrument(...)] instead of attaching spans to futures with .instrument(...) at call sites. Before adding instrumentation, check whether the callee—or the implementation method it immediately delegates to—is already instrumented.
• Avoid large modules:
  • Prefer adding new modules instead of growing existing ones.
  • Target Rust modules under 500 LoC, excluding tests.
  • If a file exceeds roughly 800 LoC, add new functionality in a new module instead of extending the existing file unless there is a strong documented reason not to.
  • This rule applies especially to high-touch files that already attract unrelated changes, such as codex-rs/tui/src/app.rs, codex-rs/tui/src/bottom_pane/chat_composer.rs, codex-rs/tui/src/bottom_pane/footer.rs, codex-rs/tui/src/chatwidget.rs, codex-rs/tui/src/bottom_pane/mod.rs, and similarly central orchestration modules.
  • When extracting code from a large module, move the related tests and module/type docs toward the new implementation so the invariants stay close to the code that owns them.
  • Avoid adding new standalone methods to codex-rs/tui/src/chatwidget.rs unless the change is trivial; prefer new modules/files and keep chatwidget.rs focused on orchestration.
• When running Rust commands (e.g. just fix or just test) be patient with the command and never try to kill them using the PID. Rust lock can make the execution slow, this is expected.