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:

Languages	TypeScript, JavaScript
Frameworks	Next.js API routes (App Router and Pages)
Convention	API routes must not import data-access clients directly
Status	Beta — local CLI and a read-only MCP server

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):

Onboards, learns the real data layer, catches an injected violation	7 / 7
Correct file:line evidence	7 / 7
A properly layered route falsely flagged	0 / 7
False-positive rate (dub, 494 routes)	3.1%
Evasion shapes caught, at the contract's mode (pnpm eval:evasion)	66 / 66 testable cells

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):

Ordinary edits refused rather than answered	0 / 56
Local imports the resolver places	96.1% – 99.9%

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 vers