drift: Instructions file for Codex

drift — agent instructions

drift is a Rust terminal UI for reviewing working changes like a pull request: everything since the base branch (committed, uncommitted, untracked) in one live view, plus real GitHub/GitLab PR review and a send-to-AI-agent integration.

Commands

cargo build                 # debug binary at target/debug/drift
cargo test                  # unit + integration tests (tests/git_vcs.rs)
cargo test <name>           # one test by substring
cargo clippy --all-targets  # must be warning-free
cargo fmt                   # required before committing

Architecture

• src/app/ — the coordinator: event loop, key dispatch, overlay state (picker, compose, help). Fully synchronous — no async runtime; background work is std::thread::spawn + an AppEvent channel.
• src/lang/ — the language registry: name, extensions, grammar, block kinds, highlight queries per language. Everything language- specific lives here. No grammar is compiled into drift: every language is a plugin (manifest + query + dylib-compiled grammar under the config dir's languages/), installed via the drift lang CLI or the in-app prompt and hot-loaded. The curated install registry is the repo's languages/ directory (manifests + drift's query stacks), embedded into the binary — adding a curated language = one manifest file there, and tests validate every entry. Unit tests see a registry built from dev-dependency grammar crates plus those curated files, so the suite runs without git or a C compiler; the crate versions in [dev-dependencies] must match the revs the curated manifests pin.
• src/processor/ — tree-sitter block scoping, syntax highlighting, view flattening (view.rs is the canonical row model). Language- agnostic: grammars and queries come from src/lang/.
• src/vcs/ — git via gitoxide; never shells out to git.
• src/forge/ — PRs through the official gh/glab CLIs; drift never speaks HTTP itself. One submodule per forge behind the Forge trait. fetch.rs is the one git call outside drift lang: the PR view's fetch prompt runs git fetch for a PR's commits, only on y.
• src/connect/ — send-to-agent backends behind the Bridge trait; one submodule per multiplexer plus a BACKENDS registry table in mod.rs. Adding a backend touches only this directory: new file, new Backend variant, one registry row.
• src/keymap.rs — bindings as data: KEY_DEFAULTS + HELP tables; tests enforce that every action is bound and appears in help.
• src/theme.rs — every color drift paints; THEME_DEFAULTS is the single source (onedark_dark palette).
• src/config.rs — ~/.config/drift/config.toml; each section is a serde struct with an into_config() validator, and default_toml() must stay parseable (a test round-trips it).