drift docs

Install

macOS & Linux — prebuilt binaries (x86_64/aarch64) land in ~/.local/bin; override the directory with DRIFT_INSTALL_DIR. The Linux binaries link against glibc (2.17+) — language plugins are loaded with dlopen, which a static binary cannot do. On musl-based distros (Alpine, etc.), install with cargo instead:

$ curl -fsSL https://tothalex.github.io/drift/install.sh | sh

Cargo — builds from source on your machine (Rust 1.96+); the package is drift-tui, the binary it installs is drift. On musl distros a native build links musl dynamically, so language plugins work (with a rustup musl toolchain add RUSTFLAGS="-C target-feature=-crt_static"):

$ cargo install drift-tui

Windows (experimental) — download drift-windows-x86_64.zip from the latest release, unzip, move drift.exe somewhere permanent, and add that folder to your user PATH. Windows Terminal is recommended.

Or build from source on any platform.

Updating — drift update installs the latest release in place (--check just reports); both print the changelog for everything between your version and the latest. drift also checks for a newer release on launch, at most once a day, and mentions it in the status bar — disable under [update]. Installs managed by cargo or homebrew are refused with the right command instead.

Usage

$ drift              # review the current repo
$ drift --base dev   # compare against a different base
$ drift ~/some/repo  # review another repository
$ drift --pr 123     # open pull request #123 right away
$ drift doctor       # check the CLIs drift drives: versions, auth

The comparison point is git merge-base <base> HEAD, diffed against the working tree — committed work, uncommitted edits, and untracked files all show up together, live as you edit. Repositories are read natively (gitoxide); the git binary is not required.

Long lines wrap at the pane edge (vim-style, hanging behind the gutter) instead of clipping. Wrapping is display-only: motions, visual mode, yanks and send-to-agent operate on real lines. In the file tree, a name clipped by a narrow pane shows its full path in a tooltip under the cursor; the review board answers a clipped commit summary or branch name the same way, and an expanded row widens the panel to fit the summaries it holds.

Generated files — lockfiles (Cargo.lock, package-lock.json, go.sum, …), minified bundles, protobuf and *.generated.* output — recede in the file tree, H / L step over them (a review never opens on one), and they don't count toward review progress. .gitattributes has the final say: linguist-generated marks more files, -linguist-generated opts one back in.

Keybindings

Press ? inside the app for this list; every binding is rebindable. Motions take vim-style counts (10j).

Navigate

Review

Pull requests

Configuration

Everything lives in ~/.config/drift/config.toml (respects $XDG_CONFIG_HOME). Generate the fully documented default file to edit from:

$ drift --init-config

Top-level entries:

[keys]
next_file = ["tab"]
yank      = ["y", "ctrl-c"]

# ~/.config/drift/config.toml
colorscheme = "mytheme"

# ~/.config/drift/themes/mytheme.toml — same keys as [theme];
# missing keys keep the built-in defaults
keyword = "#fb4934"
string  = "#b8bb26"

[rust]
bracket = "#fe8019"

[forge]
kind = "gitlab"          # or "github"
# gh = "/path/to/gh"     # binary overrides, if not on PATH
# glab = "/path/to/glab"
# viewed_sync = true     # x also ticks the file viewed on GitHub

[agent]
# backend = "auto"     # auto | herdr | tmux | cmux | off — naming one
#                      # forces it from outside that session too
# target = "claude"    # pin an agent name or pane id; empty = auto-pick
# submit = true        # false: stage the prompt without pressing enter
#                      # (cmux has no staging — it always submits)
# template = "{input}\n\n{file}:{lines}\n```\n{code}\n```"

[board]
# first = "worktrees"  # or "branches" — the list b opens on

[tree]
# layout = "groups"    # or "directories" — the layout drift starts in

[picker]
# width = "80%"        # ceilings, not fixed sizes
# height = "80%"

[update]
# check = true         # look for a newer release on launch (at most
#                      # once a day) and mention it in the status bar

Language plugins

Every language is a plugin: a tree-sitter grammar fetched and compiled on your machine, plus a highlight query — no grammar is compiled into drift itself. The first time drift shows a file whose language is available but not installed, it offers it right there: press y and keep reviewing while the grammar builds in the background — highlighting and block scoping appear in place when it's ready; n declines for the session. Files without an installed language review as plain hunks.

The same works from the command line. Installing needs git and a C compiler — the only place drift uses a compiler (and, besides the pull-request fetch prompt, git).

$ drift lang install rust    # curated: bash, c, cpp, csharp, css, dockerfile,
                             #   go, html, java, javascript, json, lua, markdown,
                             #   php, python, ruby, rust, toml, tsx, typescript,
                             #   yaml
$ drift lang install https://github.com/tree-sitter-grammars/tree-sitter-zig
$ drift lang list            # installed and installable
$ drift lang build           # rebuild grammars (after a drift upgrade)
$ drift lang remove rust

For the languages drift curates deeply (rust, typescript, tsx, javascript, python, go) the installed highlights.scm is drift's full query stack — the grammar's bundled queries plus hand-tuned supplements that close the gaps against editor-grade highlighting — and it's yours to edit. Other languages get the grammar repo's bundled query.

A plugin is a directory under ~/.config/drift/languages/<name>/; compiled grammars are cached in ~/.cache/drift/grammars/.

# ~/.config/drift/languages/zig/language.toml
name = "zig"
extensions = ["zig", "zon"]

[grammar]
repo = "https://github.com/tree-sitter-grammars/tree-sitter-zig"
rev = "…"              # commit to build; default branch if unset
# path = "zig"                 # subdirectory, for repos hosting several grammars
# symbol = "tree_sitter_zig"   # exported fn; tree_sitter_<name> if unset
block_kinds = ["function_declaration", "if_statement"]

block_kinds lists the grammar's node kinds that count as reviewable blocks — what changes expand to and what [/] widen through: functions, classes, loops. drift lang build warns about node kinds the grammar doesn't actually have, and validates the highlight query against the freshly built grammar.

• Curated languages are complete manifests (and query stacks) in the repo's languages/ directory, embedded into the binary — adding one upstream is a one-file PR. URL installs scaffold the manifest and point out what to fill in.
• Every installed language's name works in [theme.<lang>] sections.
• A broken plugin never stops drift — it degrades to a startup warning and plain hunk view for its files. After a drift upgrade changes the tree-sitter ABI, drift lang build rebuilds everything.

Grammars are native code compiled into a library that drift loads — install only grammars you trust.

Pull requests

Press p (or run drift --pr 123) to browse the repo's open pull requests (GitHub) or merge requests (GitLab) — the same file tree, block-scoped diffs, review progress, and search as the primary view, with the whole conversation in place: inline threads under the exact lines they were written on, a pinned # conversation entry for the description and PR-level discussion, replying, resolving, and deleting without leaving the terminal.

Setup is the forge's own CLI — install one and authenticate once:

$ gh auth login    # GitHub — https://cli.github.com
$ glab auth login  # GitLab — https://gitlab.com/gitlab-org/cli

That is also what makes GitHub Enterprise and self-managed GitLab work: authenticate the CLI against your host (gh auth login --hostname git.corp.example) and drift picks the forge from the repo's origin remote — see [forge] for hosts naming neither.

When the PR's commits exist locally, diffs get full syntax highlighting and block scoping. When they don't, drift offers to fetch them: y runs git fetch origin pull/<n>/head (GitLab: merge-requests/<n>/head) in the background — objects only, no branch or worktree changes — and the views fill in when it lands; n keeps plain hunks for that PR. Nothing is fetched without asking, and the fetch never prompts for credentials in drift's terminal. Large pull requests open too: past GitHub's size limit for a whole diff, drift loads it file by file, and a single file the forge leaves out as too large says so in place of its diff rather than passing for unchanged.

AI agents

Select lines (or sit on one), press s, type an instruction — the prompt lands in the Claude Code (or Codex, or any agent) pane beside drift, with the file location and the code attached. A selection that covers a change is sent unified-diff style — - old lines, + new lines.

This works through herdr, a terminal workspace manager for AI coding agents — or through plain tmux, or cmux. In herdr, drift finds every agent pane automatically, with its live idle/working state; in tmux and cmux, agent panes are recognized by their running process (claude, codex, aider, …) with the same closest-first targeting, minus the idle/working state. Auto-detection takes the innermost session drift runs inside — herdr or tmux ahead of the cmux surface holding them — and naming a backend (backend = "tmux") forces it from any terminal, except cmux, whose socket answers only its own surfaces unless you widen its socketControlMode setting.

The review board's agent column is herdr-only for the same reason: herdr reports each agent's session id, so drift can read the session's own record and put the agent on the worktree its latest turn changed — whether it moved into a worktree of its own (.claude/worktrees/…) or never left the main checkout and edits another by path. Subagents and workflow agents count toward the session that launched them, and several agents in one worktree show as the busiest plus a count (● claude working +1). A pane's own directory never moves with its agent, so the other backends would credit the work to the checkout the agent was launched from.

• An agent split in drift's own tab is picked automatically — the drift-beside-claude layout never shows a picker.
• With several sessions, a picker asks (closest first, each row naming where its agent is); ↑↓ re-aim the prompt while composing, and the title follows.
• The choice sticks: later sends aim at the same session until its pane goes away. Pin one for good with agent.target.

drift drives these sessions through their own CLIs; herdr must be 0.7.5 or newer (older releases predate the pane commands drift sends through). drift doctor checks every external CLI — version, required minimum, auth.

Build from source

$ cargo build --release   # binary at target/release/drift
$ cargo test

Git repositories are read natively (via gitoxide) — the git binary is not required to review. Only drift lang install/build shell out to git and a C compiler, to fetch and compile grammar plugins — and the pull-request view's fetch prompt, to git fetch a PR's commits when you accept it.