Repository Guidelines

Workflow Principles

• NEVER use git to discard or revert any changes not made by you - they are proposely changed by user and you should live with that.

Engineering Rules

This project requires extremely high code quality and maintainability. Best engineering practices must be followed at all times.

The rules below are some typical principles. They are not exhaustive, and you must always use your best judgment to write the cleanest code possible. You must always clean up and refactor immediately when you see opportunities or any violations of these engineering rules.

Core Principles: Simplicity & Readability

• Boring Code - Obvious, self-explanatory > clever, minimize cognitive load
• Single Responsibility - One function, one job
• Explicit over Implicit - Clear is better than concise
• Meaningful Abstractions - Only when they reduce cognitive load
• Keep DRY - Only if it does not conflict with the above principles

Better Maintainability

• Keep the public API surface minimal; prefer reusing existing methods
  • Don't use pub(crate), use pub.
• Don't treat "looks similar" as "equivalent"
• Abstractions must be meaningful
• Keep certainty, single source of truth - e.g. don't introduce "optional" unless absolutely necessary
• Always add clear, concise and explicit doc comments for public APIs, complex logic, and non-obvious code

Naming Symbols

• Choosing the name that needs the least explanation, consider: verb clarity, noun specificity, context
• Name tests by behavior and expectation (e.g. test_restore_keyspace_with_failed_store).

Project Conventions

• When using format! and you can inline variables into {}, always do that.
• 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
• When writing tests, prefer comparing the equality of entire objects over fields one by one.
• Always use English for code, comments, commit messages, PR titles/descriptions, and documentation.
• Keep interactive behavior parity between a fresh interactive session and codex-potter resume during live iteration (replay is exempt). E.g. Esc during a running round should interrupt and reach the same Stop/Continue decision prompt, Stop should insert the interrupted summary block, and user-requested exit should print the same resume hint.
• tui/ module must only contain pure UI rendering logic. Business logic must not be placed there.
• IMPORTANT: When working with tui/, must follow conventions in tui/AGENTS.md strictly.
• Run cargo fmt and cargo clippy before committing code.

Upstream Maintaining

TUI crate is supposed to be a subset of upstream codex's TUI crate, and you must keep it as close as possible to the upstream's codebase, so that we can easily sync from upstream and reduce merge conflicts. tui/AGENTS.md describes intended divergences in behavior and code between codex-potter and upstream code. tui/AGENTS.md also describes other conventions for TUI code and tests. You must follow them strictly when working on TUI code.

If not specified, upstream codex should be available at ../codex relative to this repo.

Tests

Snapshot tests

This repo uses snapshot tests (via insta), especially in tui, to validate rendered output. When UI or text output changes intentionally, update the snapshots as follows:

• Run tests to generate any updated snapshots:
  • cargo test -p codex-tui
• Check what’s pending:
  • cargo insta pending-snapshots --manifest-path tui/Cargo.toml
• Review changes by reading the generated *.snap.new files directly in the repo, or preview a specific file:
  • cargo insta show --manifest-path tui/Cargo.toml path/to/file.snap.new
• Only if you intend to accept all new snapshots in this crate, run:
  • cargo insta accept --manifest-path tui/Cargo.toml

If you don’t have the tool:

• cargo install cargo-insta

Test assertions

• Tests should use pretty_assertions::assert_eq for clearer diffs. Import this at the top of the test module if it isn't already.
• Prefer deep equals comparisons whenever possible. Perform assert_eq!() on entire objects, rather than individual fields.
• Avoid mutating process environment in tests; prefer passing environment-derived flags or dependencies from above.