Drift

Drift stops an AI agent from writing code that violates conventions your repo already follows. It runs entirely on your machine.

Beta install: build from source. Nothing is published to npm yet — npm install -g @drift/cli does not work, and the driftdetect package on npm is the unrelated v1 from January. Building needs a Rust toolchain (rustup) because the scan engine is Rust.

git clone https://github.com/dadbodgeoff/drift.git && cd drift
pnpm install --frozen-lockfile
pnpm build && pnpm build:engine

# There is no `drift` binary yet; the entry point is the built CLI.
alias drift="node $PWD/packages/cli/dist/main.js"
drift doctor --repo-root .          # fails loudly if the toolchain is missing

Then, in the repository you want to protect:

cd your-repo
drift start --repo-root . --accept-defaults

start prints whether the convention it accepted will actually block, and the command to make it a gate if it will not. Now have an agent add a route that queries the database directly, the way a hundred other routes in your repo do not, and check the change:

drift check --diff HEAD~1...HEAD --scope changed-hunks

It names the file, the line, and the convention that was broken. In block mode it exits 2.

--diff main...HEAD only works once your branch has commits that main does not. On a freshly cloned repo you are on main, so that range is empty and Drift refuses rather than reporting a pass it cannot support — exit 3. That refusal is correct; give it a range with changes in it.

Scope — read this before adopting

Drift enforces one convention family well, and says so rather than implying more:

It does not review code generally, support other languages, modify your source, or sync anything to a server.

The data layer is recognised when its import specifier contains prisma, database, db or data-access. A repo naming its data layer store or supabase must declare it with --data-modules. Drift bootstraps and enforces a declared layering contract — it does not learn conventions in general, and the claims manifest blocks that claim explicitly.

Security heuristics exist behind --experimental-security and are not proofs. Their own audit is in docs/internal/architecture/security-heuristic-audit.md.

What it does on real repositories

Evaluated on seven open-source Next.js repos on every change (pnpm eval:external):

And, because the number that decides whether a first session is tolerable is not recall but how often Drift declines to answer — eight ordinary edits per repo, none of them a violation (pnpm eval:bench):

Every check reports its own coverage, so a clean result is never mistaken for full coverage. Where Drift cannot resolve something it says so, with the offending specifiers — see drift doctor and summary.import_coverage.

Why your repo might only warn

If findings appear but the check exits 0, the convention is in warn mode, deliberately.

Drift infers the convention from the violations themselves, so a repo where every route touches the database produces the same statement as one where a single route does. Enforcing both identically would reject new code written exactly like its neighbours. Instead the mode follows the evidence: a minority violating means new violations block; a majority violating means it is a refactor goal, and Drift warns until a human decides.

formbricks (1 route of 83) blocks. dub (~323 of 494) warns.

Documentation

• Quickstart — install to first blocked change
• Concepts — facts → contract → baseline → check
• Agent integration — MCP, hooks, CI
• Enforcement reference — exit codes and JSON contract
• Claims — every claim, and what is deliberately blocked
• History — why Drift has been rebuilt three times, and what changed each time

First Five Minutes

From the repo you want Drift to inspect:

drift doctor --repo-root .
drift start --repo-root . --accept-defaults
drift doctor --repo-root .

The first doctor run is a zero-write readiness check. After start, run it again as the ongoing local health gate: it validates SQLite migration compatibility, repo registration, contract compatibility, scan freshness, audit-chain integrity, and tracked backup artifacts, then prints the next upkeep commands.

start --accept-defaults is explicit onboarding confirmation. It accepts the deterministic default convention, materializes the repo contract, and baselines existing findings so legacy drift does not block the first check. Omit --accept-defaults when you want to review every candidate manually first.

drift start prints the local SQLite path:

export DRIFT_DB=/path/to/drift.sqlite

Then use the printed repo id with the review loop:

drift baseline status --repo <repo_id>
drift version --json
drift capabilities --json
drift conventions list --repo <repo_id> --status candidate --kind api_route_no_direct_data_access --capability deterministic_check --limit 20 --offset 0 --json
drift conventions accepted --repo <repo_id> --kind api_route_no_direct_data_access --capability deterministic_check --limit 20 --offset 0 --json
drift conventions show <candidate_id> --repo <repo_id> --json
drift ask "what should I know before changing this route?" --repo <repo_id> --path apps/web/app/api/users/route.ts --json
drift prepare "add user search endpoint" --repo <repo_id> --path apps/web/app/api/users/route.ts --json
drift repo map --repo <repo_id> --role api_route --json
drift repo map --repo <repo_id> --limit 50 --offset 0 --json
drift prepare "add user search endpoint" --repo <repo_id> --require-fresh --json
drift checks list --repo <repo_id> --limit 20 --offset 0 --json
drift checks run --repo <repo_id> --command "pnpm test" --timeout-ms 120000 --json
drift policy check-context --repo <repo_id> --path apps/web/app/api/users/route.ts --surface cli-preflight --require-fresh --json
drift check --diff main...HEAD --repo <repo_id> --scope changed-hunks
drift findings list --repo <repo_id>
drift findings list --repo <repo_id> --convention <convention_id> --json
drift findings list --repo <repo_id> --path apps/web/app/api/users/route.ts --require-fresh --json
drift findings list --repo <repo_id> --limit 25 --offset 0 --json
drift findings show <finding_id> --repo <repo_id> --require-fresh --json
drift backup create --repo <repo_id> --confirm
drift backup list --repo <repo_id> --json
drift backup list --repo <repo_id> --limit 20 --offset 0 --json
drift backup list --repo <repo_id> --artifact-status missing --json
drift audit list --repo <repo_id>
drift audit verify --repo <repo_id> --json
drift audit list --repo <repo_id> --target-id <repo_id> --limit 20 --offset 0 --json
drift audit list --repo <repo_id> --since 2026-05-10T00:00:00.000Z --until 2026-05-11T00:00:00.000Z

Backup output prints the verify and restore dry-run commands. Backup list, verify, and restore JSON also include compact summaries so setup scripts can see artifact health, checksum status, restore intent, and rescan requirements without parsing prose:

drift backup verify <backup.sqlite> --repo <repo_id> --checksum <sha256>
drift backup verify <backup.sqlite> --repo <repo_id> --checksum <sha256> --require-checksum
drift --db <target.sqlite> restore <backup.sqlite> --repo <repo_id> --checksum <sha256> --dry-run
drift --db <target.sqlite> restore <backup.sqlite> --repo <repo_id> --checksum <sha256> --require-checksum --dry-run

For stricter restore identity checks, pass the expected repo fingerprint:

drift backup verify <backup.sqlite> --repo <repo_id> --expect-repo-fingerprint <fingerprint>
drift --db <target.sqlite> restore <backup.sqlite> --repo <repo_id> --expect-repo-fingerprint <fingerprint> --dry-run

Contract exports can stay on stdout or be written to one approved artifact:

drift contract export --repo <repo_id> --format json --output ./repo-contract.json --confirm
drift contract import ./repo-contract.json --dry-run
drift contract import ./repo-contract.json --checksum <sha256> --dry-run
drift contract import ./repo-contract.json --checksum <sha256> --require-checksum --dry-run

contract show, contract validate, contract export, contract import --dry-run, and MCP get_repo_contract expose a stable contract_fingerprint for compatibility checks. The fingerprint is computed from canonical contract content, so unordered governance lists do not create false drift.

scan status, prepare, MCP get_scan_status, and MCP get_task_preflight expose a stable scan_fingerprint for the indexed graph plus no-approval governance metadata, summary counts, indexed_file_count, source_change_count, audit integrity, and next commands. Agents can compare the fingerprint before acting and after rescans without