Skip to content
Back to search

drift

Codebase intelligence for AI. Detects patterns & conventions + remembers decisions across sessions. MCP server for any IDE. Offline CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 16 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/dadbodgeoff/drift with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/dadbodgeoff/drift'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dadbodgeoff--drift/badge.svg)](/listings/dadbodgeoff--drift)

HTML

<a href="/listings/dadbodgeoff--drift"><img src="/api/listings/dadbodgeoff--drift/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Nothing is published yet: there is no npm package and no release archive. Until the first release, use one of the two paths below. Both end at `drift --version`.

**A binary a teammate gave you.** It must be built for your operating system and CPU. Put it in a directory on your `PATH` and make it executable:

mkdir -p ~/.local/bin
cp ./drift ~/.local/bin/drift && chmod +x ~/.local/bin/drift
drift --version

If `drift` is not found, add `~/.local/bin` to your `PATH`. Install it as `drift` on your `PATH`, not only in one directory: the Claude Code hooks and the pre-commit hooks run `drift` from your `PATH`.

**Build from source.** From a checkout of this repository, with Rust 1.97 (`rust-toolchain.toml` pins it, and `rustup` fetches it the first time you run cargo inside the checkout):

cargo install --locked --path crates/drift-cli     # a release build: several minutes

This installs the `drift` binary into `~/.cargo/bin`, which `rustup` puts on your `PATH`.

drift --version

**After the first release.** Neither of these works today (the npm package returns 404 and no archive exists):

npm install -g @dadbodgeoff/drift     # prebuilt binary, no install scripts

A beta (prerelease) version will be published under npm's `next` dist-tag, not `latest`: `npm install -g @dadbodgeoff/drift@next`. For a one-off run without installing, `npx @dadbodgeoff/drift census`. Plain `npx drift` runs a project-local install only; without one, npm would fetch an unrelated package named `drift`.

Each GitHub Release will have one archive per platform, `drift-vX.Y.Z-<target>.tar.gz` (targets `x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`, `x86_64-apple-darwin`, `aarch64-apple-darwin`, `x86_64-pc-windows-msvc`), each holding the one `drift` (or `drift.exe`) binary, plus `SHA256SUMS` and SLSA build provenance. Verify, then put it on your `PATH`:

sha256sum -c SHA256SUMS --ignore-missing
gh attestation verify drift-vX.Y.Z-<target>.tar.gz --repo dadbodgeoff/drift
tar -xzf drift-vX.Y.Z-<target>.tar.gz && mv drift ~/.local/bin/    # any directory on PATH

The binaries are not code-signed or notarised; the checksums and provenance are what you can verify. See [RELEASING.md](RELEASING.md).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "drift",
  3. "owner": { "name": "Drift" },
  4. "description": "Drift: the convention lockfile for AI agents.",
  5. "plugins": [
  6. {
  7. "name": "drift",
  8. "source": "./integrations/claude-code",
  9. "description": "Learned conventions for Claude Code: rules before writing, advice after editing, and a block at the end of the turn for conventions you set to block."
  10. }
  11. ]
  12. }
README.md · README · 828 lines
  1. # Drift
  2. **The convention lockfile for AI agents: mined from your code, approved by you, checked in your agents and CI.**
  3. Drift is a command-line tool that reads a repository and learns the conventions
  4. the code already follows, such as the wrapper every API route uses, the guard
  5. every server action calls or the layout every page renders. You confirm them;
  6. Drift then tells coding agents about the ones you accepted (a suggestion also
  7. needs `drift review --show-to-agents`) and reports new code that breaks them, and blocks only the ones you set to block. It ships no
  8. predefined rules, runs no AI in the check path, and never sends your source
  9. code anywhere: it reads the working tree and writes under `.drift/` and
  10. `drift.lock`.
  11. > **Status: beta.** Drift learns the conventions of TypeScript, JavaScript and
  12. > Python code, shows them to you first, tells coding agents
  13. > only about the ones you accept, and plugs into Claude Code, pre-commit, GitHub
  14. > code scanning and any MCP client.
  15. >
  16. > - **Agents see only what a person accepted, and chose to show.** Default-tier
  17. > proposals are *block candidates*: they reach agents once you accept them
  18. > (decision D13). A suggestion (every Python convention is one) reaches agents
  19. > only after `drift review --show-to-agents <id>`, unless its rule family is
  20. > admitted (none is today).
  21. > - **Nothing blocks** unless a person sets it to block.
  22. > - **Mined Python proposals are on by default, as suggestions only**
  23. > (`proposals: {python: off}` turns them off). A blind check of 11 cards
  24. > decided the default; it is not a held-out result.
  25. > - **Review every proposal.** On repositories Drift was not tuned on, about half
  26. > of the default-tier cards (7 of 15) and 6 of 7 shown suggestions were right:
  27. > small samples, and below the ≥ 95% release gate. See
  28. > [How accurate is it?](docs/ACCURACY.md) and
  29. > [Accuracy and limits](#accuracy-and-limits).
  30. >
  31. > [Beta release notes](docs/RELEASE-NOTES-beta.md) · [plan](docs/v2/PLAN.md)
  32. **Documentation.** This page is the front door. The full guide is the wiki
  33. pages under [`docs/wiki/`](docs/wiki/Home.md): start at [Home](docs/wiki/Home.md), or
  34. go straight to [Getting started](docs/wiki/Getting-Started.md),
  35. [Drift in CI](docs/wiki/Drift-in-CI.md), [Team rollout](docs/wiki/Team-Rollout.md),
  36. the [command reference](docs/wiki/Command-Reference.md) or
  37. [Troubleshooting](docs/wiki/Troubleshooting.md).
  38. ## Contents
  39. - [What Drift does and how sure it is](#what-drift-does-and-how-sure-it-is)
  40. - [Install](#install)
  41. - [A five-minute first run](#a-five-minute-first-run)
  42. - [Drift inside git](#drift-inside-git)
  43. - [The commands at a glance](#the-commands-at-a-glance)
  44. - [Configuration at a glance](#configuration-at-a-glance)
  45. - [Using Drift with agents](#using-drift-with-agents)
  46. - [Accuracy and limits](#accuracy-and-limits)
  47. - [Drift Studio](#drift-studio)
  48. - [Design and safety](#design-and-safety)
  49. - [Contributing, support and license](#contributing-support-and-license)
  50. ## What Drift does and how sure it is
  51. Drift does five things, all locally. It **mines** the conventions your code
  52. follows and proposes them as rules for you to review (`drift init`,
  53. `drift census`, `drift review`, `drift check`). It **maps** what the code does
  54. per route for authentication, authorization, error handling, logging, validation
  55. and more (`drift practices`). It **inventories** entry points with their guards
  56. and where they are reachable from (`drift security`). It **gives agents** a
  57. file's place and rules (`drift card`, `drift mcp`, the Claude Code hooks). And it
  58. **asks** the few questions only a person can answer, such as whether a compose
  59. file deploys anything (`drift setup`).
  60. **How sure are the answers?** Not equally. Exposure (internet-facing, internal,
  61. unknown) and error handling are in good shape. For authentication and
  62. authorization, `known` is proven, but on code Drift was not tuned on a share of
  63. `none` answers (and some `known`) are wrong: independent, unseen test suites
  64. found 9% to 15% of soundness checks (about one in seven to one in eleven)
  65. wrong on first contact. Read
  66. `none` and `internal` as "nothing found in what Drift read": a finding to check,
  67. not a fact. `unknown` means Drift could not tell and says why; it is common, and
  68. it is the honest answer. Mined conventions are proposals, and about half of the
  69. default-tier ones were wrong out of sample, which is why a person reviews every
  70. one. Details: [Accuracy and limits](#accuracy-and-limits) and
  71. [Accuracy and Limits](docs/wiki/Accuracy-and-Limits.md).
  72. ## Install
  73. Nothing is published yet: there is no npm package and no release archive. Until
  74. the first release, use one of the two paths below. Both end at `drift --version`.
  75. **A binary a teammate gave you.** It must be built for your operating system and
  76. CPU. Put it in a directory on your `PATH` and make it executable:
  77. ```sh
  78. mkdir -p ~/.local/bin
  79. ```
  80. ```sh
  81. cp ./drift ~/.local/bin/drift && chmod +x ~/.local/bin/drift
  82. ```
  83. ```sh
  84. drift --version
  85. ```
  86. If `drift` is not found, add `~/.local/bin` to your `PATH`. Install it as
  87. `drift` on your `PATH`, not only in one directory: the Claude Code hooks and the
  88. pre-commit hooks run `drift` from your `PATH`.
  89. **Build from source.** From a checkout of this repository, with Rust 1.97
  90. (`rust-toolchain.toml` pins it, and `rustup` fetches it the first time you run
  91. cargo inside the checkout):
  92. ```sh
  93. cargo install --locked --path crates/drift-cli # a release build: several minutes
  94. ```
  95. This installs the `drift` binary into `~/.cargo/bin`, which `rustup` puts on your
  96. `PATH`.
  97. ```sh
  98. drift --version
  99. ```
  100. **After the first release.** Neither of these works today (the npm package
  101. returns 404 and no archive exists):
  102. ```sh
  103. npm install -g @dadbodgeoff/drift # prebuilt binary, no install scripts
  104. ```
  105. A beta (prerelease) version will be published under npm's `next` dist-tag, not
  106. `latest`: `npm install -g @dadbodgeoff/drift@next`. For a one-off run without
  107. installing, `npx @dadbodgeoff/drift census`. Plain `npx drift` runs a
  108. project-local install only; without one, npm would fetch an unrelated package
  109. named `drift`.
  110. Each GitHub Release will have one archive per platform,
  111. `drift-vX.Y.Z-<target>.tar.gz` (targets `x86_64-unknown-linux-musl`,
  112. `aarch64-unknown-linux-musl`, `x86_64-apple-darwin`, `aarch64-apple-darwin`,
  113. `x86_64-pc-windows-msvc`), each holding the one `drift` (or `drift.exe`)
  114. binary, plus `SHA256SUMS` and SLSA build provenance. Verify, then put it on
  115. your `PATH`:
  116. ```sh
  117. sha256sum -c SHA256SUMS --ignore-missing
  118. gh attestation verify drift-vX.Y.Z-<target>.tar.gz --repo dadbodgeoff/drift
  119. tar -xzf drift-vX.Y.Z-<target>.tar.gz && mv drift ~/.local/bin/ # any directory on PATH
  120. ```
  121. The binaries are not code-signed or notarised; the checksums and provenance are
  122. what you can verify. See [RELEASING.md](RELEASING.md).
  123. ## A five-minute first run
  124. Run these in the repository you want Drift to learn, on a clean working tree.
  125. Nothing leaves your machine, nothing reaches an agent until a person accepts it
  126. (a suggestion needs one more step, below), and nothing blocks until you say so.
  127. ```sh
  128. drift census # preview: what Drift would propose; writes nothing
  129. ```
  130. ```sh
  131. drift init # write the proposals to .drift/conventions.yaml, baseline drift.lock
  132. ```
  133. On a small synthetic Next.js-style repository with 40 route handlers, 38 of them
  134. wrapped in `withAuth()` (the one `npm/dry-run.sh` builds), `drift init` prints:
  135. ```
  136. Drift read 71 files of TypeScript and JavaScript. Nothing left this machine.
  137. What the code does (read from the code: facts, not rules)
  138. 40 http entry points
  139. sign-in: wrapped in withAuth in 38; nothing found in 2 (of 40)
  140. permissions: nothing found in 38 (of 38 where a caller is or may be signed in)
  141. errors: left to the framework in 40 (of 40)
  142. responses: built with Response.json in 40 (of 40)
  143. Worth a look first
  144. 1. sign-in: no guard found in what Drift read, in 2 places (e.g. app/api/r38/route.ts:1 GET); make the usual way the rule for new code: drift practices promote P-0f0acb --in .
  145. `drift security` lists every entry point with its guard and what it reaches. `drift practices promote --list` lists the practices you can make a rule for new code.
  146. Conventions
  147. 1 proposed (1 default tier, 0 suggestions). Nothing is checked and no agent is told of one until you decide (`drift review`); an accepted convention advises unless you set it to block.
  148. Default tier: block candidates, each reaches agents once you accept it, and may block once accepted (`drift review`, b)
  149. 1. [D-37416b] HTTP handlers in app/** (route files) are wrapped in withAuth()
  150. evidence: 38/40 (lower bound 0.83, lift 1.8)
  151. tier: default
  152. agents: not shown to agents (block candidate: reaches agents once you accept it)
  153. example: app/api/r00/route.ts#GET
  154. outlier: app/api/r38/route.ts:1 GET
  155. outlier: app/api/r39/route.ts:1 GET
  156. Wrote .drift/conventions.yaml and drift.lock (2 existing violations recorded, so only new ones are reported).
  157. Next
  158. drift review accept or reject the 1 proposal
  159. drift practices the whole map, with a file to copy for each way
  160. drift security entry points, their guards and the risky operations they reach
  161. Tip: add `drift.lock merge=union` to .gitattributes so branches never conflict on the lock.
  162. ```
  163. The first part is what Drift read in the code, whether or not it has anything to
  164. propose: each kind of entry point, how its members sign a caller in, check
  165. permissions, handle errors and answer, and the few things most worth a look.
  166. These are facts, not rules: nothing checks them until a person promotes one
  167. (below). `Conventions` is what Drift
  168. proposes to check from now on, and `Next` lists only the commands that have
  169. something to do here. `drift init --explain` adds the long account: what the
  170. show policy held back and why, package by package.
  171. Everything starts as a proposal, and a proposal is not checked at all. Read each
  172. card's outliers: if they are mistakes, accept the convention; if they are a
  173. legitimate, different kind of member (a test helper, a config file), reject it
  174. or set those members apart. Small or uniform repositories often get no
  175. proposals, and `drift init` then says why.
  176. If `drift init` says weaker candidates were kept back, list them first (`drift review --hidden`; see **No proposals?** below): interactive review then says so and stops.
  177. ```sh
  178. drift review # interactive, needs a terminal: y accept (advise), b accept and block, a accept and show to agents, n reject, s skip, q quit
  179. ```
  180. ```sh
  181. drift check # new violations of accepted conventions; exit 1 only for those in block mode
  182. ```
  183. With `D-37416b` accepted in advise mode, a new route without the wrapper is
  184. reported and the exit code is 0 (after these lines `drift check` lists, as facts
  185. that never fail it, the files that sign a caller in another way than the entry
  186. points around them):
  187. ```
  188. drift: 1 new violation(s) (2 legacy, baselined)
  189. [D-37416b] HTTP handlers in app/** (route files) are wrapped in withAuth() (38/40)
  190. at app/api/new/route.ts:1 GET
  191. like app/api/r00/route.ts#GET
  192. mode advise
  193. Advice: follow a convention where it fits the code; where it does not, no action is needed (no change, no comment). Wrong convention: `drift review --reject <id>`.
  194. ```
  195. After `drift review --block D-37416b` the same check exits 1. For an
  196. intentional exception, put `// drift-ignore D-37416b: <reason>` (`#` in Python)
  197. directly above the declaration; a reason is required and suppressions are
  198. counted so reviewers see them.
  199. **Make a practice the rule.** The practice map at the top of `drift init` is
  200. facts: nothing checks them. When one is the rule you want for new code, promote
  201. it in one step. On the sample repository, sign-in in `app/api` (38 of 40 routes
  202. use `withAuth`, variant `P-0f0acb`):
  203. ```sh
  204. drift practices promote P-0f0acb --in app/api --dry-run # the preview; writes nothing
  205. ```
  206. ```sh
  207. drift practices promote P-0f0acb --in app/api # write it
  208. ```
  209. It writes one accepted convention in advise mode, shown to agents, and records
  210. the 2 routes that differ today in `drift.lock`, so `drift check` reports only a
  211. new route there that signs the caller in another way or not at all. A route
  212. Drift cannot read is never reported. It qualifies only where one way holds at
  213. least 80% of at least 8 units Drift could read, with at most 20% unknown;
  214. `drift practices promote --list` lists what qualifies now. Block mode
  215. (`--block`) is allowed only when at least 80% of the 15 routes most recently
  216. added there follow it, which needs git history. Upgrade every machine and CI first: an older Drift
  217. cannot read the policy file once it holds a promoted practice. See
  218. [Practices map](docs/wiki/Practices-Map.md#promoting-a-practice-to-a-convention).
  219. `drift review` with no flags needs a terminal: without one it prints
  220. `drift review needs a terminal` and exits 2. In a script, pass ids:
  221. `drift review --accept <id>` (`--list` prints the cards). Accepting a suggestion
  222. does not show it to agents: run `drift review --show-to-agents <id>` for that.
  223. **No proposals?** If `drift init` says `No conventions shown` and that it found
  224. candidates with no track record strong enough to propose, the show policy held
  225. back every card it mined (on one 5,858-file monorepo, all 12). They are not conventions yet: nothing checks them
  226. and no agent is told them. List them with their evidence, promote the ones that
  227. are right, and show them to agents:
  228. ```sh
  229. drift review --hidden
  230. ```
  231. ```sh
  232. drift review --hidden --answer D-59eaf5=same
  233. ```
  234. ```sh
  235. drift review --show-to-agents D-59eaf5
  236. ```
  237. The answers are `ID=same` (accept), `ID=different --set-apart PATHS` (accept,
  238. those files exempt as a different kind) and `ID=not-a-convention` (reject). See
  239. [Getting started](docs/wiki/Getting-Started.md#if-drift-init-says-no-conventions-shown-and-that-candidates-were-kept-back).
  240. On a repository of several thousand files each command reads the repository and
  241. takes tens of seconds (5,858 files: `init` 24.7 s, `check` 8.7 s, `setup --list`
  242. 28.2 s, measured on one monorepo); interactive `drift setup` reads first and then
  243. asks, so its first question comes after about 25 to 35 s.
  244. Two more commands finish the first run. If `drift init` ends with "N questions
  245. only you can answer would make these answers sharper", run `drift setup`: it asks
  246. one question at a time, "skip" is always the default and writes nothing, and the
  247. answers go to `.drift/config.yaml`. Then commit what Drift wrote (see the next
  248. section for what to commit).
  249. ```sh
  250. drift setup
  251. ```
  252. Full walk-through: [Getting started](docs/wiki/Getting-Started.md),
  253. [Conventions and review](docs/wiki/Conventions-and-Review.md) and
  254. [Setup questions](docs/wiki/Setup-Questions.md).
  255. ### Investigate what Drift could not settle
  256. `drift setup` asks a handful of questions. For every other route whose
  257. authentication, authorization or reach Drift could not settle (`unknown`, or a
  258. `none` or `internal` that is only "nothing found in what Drift read"),
  259. `drift investigate` lists the route with the evidence to read, grouped by what
  260. would settle it. It is meant for an agent to work through, with a person
  261. confirming:
  262. ```sh
  263. drift investigate # the open items; changes nothing
  264. ```
  265. ```sh
  266. drift investigate --agent-brief # the instructions an agent follows
  267. ```
  268. ```sh
  269. drift investigate --record I-1a2b3c=not-a-check --reason "..." --evidence app/svc.py:40
  270. ```
  271. An outcome follows the same rule as `drift setup`: one that only keeps or raises
  272. Drift's caution takes effect (`not-a-guard`, `not-a-check`, `reachable`,
  273. `skip`), and one that would make a fact (`guard:<file>#<symbol>`,
  274. `check:<kind>:<file>#<symbol>`, `internal`) is a proposal that waits for a person
  275. in `drift setup --review`. An unknown never becomes `none`. A real gap in the
  276. code becomes a local finding in `.drift/findings/`, and a construct Drift does
  277. not read becomes a local gap report in `.drift/gap-reports/`. Both directories
  278. ignore themselves, and nothing is ever posted or sent. `drift findings` lists
  279. them; on a person's request `drift findings --issue ID` prints an issue draft and
  280. `drift findings --branch ID` makes a local branch with the agent's patch.
  281. See [Using Drift with agents](docs/wiki/Using-Drift-with-Agents.md#investigating-open-routes).
  282. ## Drift inside git
  283. Drift works on a git working tree and never changes git. This section says what
  284. it reads, what it writes, what to commit, how branches and merges behave, and
  285. how it fits pull requests, pre-commit, CI, monorepos and agent sessions. It was
  286. checked against the code and run on a scratch repository.
  287. ### What Drift reads
  288. - **The working tree, not history.** `drift init`, `census`, `check`,
  289. `security`, `practices`, `card` and `map` read the files as they are on disk,
  290. including uncommitted edits and untracked files. They do not read commits,
  291. other branches, the index or stashes.
  292. - **`.gitignore` and `.ignore` are honoured**, in every directory. Global ignore
  293. rules and `.git/info/exclude` are not, so the result does not depend on the
  294. machine. Drift never enters `node_modules`, `.git`, `.next`, `.turbo`,
  295. `.drift`, `dist` or `build`, never follows symlinks out of the repository,
  296. skips files over 1 MB, and skips generated and minified code, including paths
  297. that `.gitattributes` marks `linguist-generated`. An ignore file that is a
  298. FIFO, a device or a link out of the repository makes Drift skip that directory
  299. with a warning.
  300. - **Git itself is run in a few places, read-only.** `drift check --diff-base`
  301. and `drift security --diff-base` call `git diff`, `git merge-base` and
  302. `git rev-parse`, and, only when a new violation outside the diff would fail the
  303. check, `git read-tree` with `git checkout-index` into a temporary directory
  304. and a temporary index to scan the merge base (your working tree and index are
  305. never touched). The agent hooks ask which files changed since `HEAD` or are
  306. untracked. Drift runs `git ls-files` once to check that no one committed the
  307. fact cache. None of these fetches from a remote.
  308. - **History is read in two cases only:** the experimental wiring rules
  309. (`experimental: [wiring]` in `.drift/config.yaml`) read the newest commits of
  310. `HEAD` to learn which files change together. History is off by default, bounded
  311. in time and size, and never fetched; a shallow or partial clone gives no
  312. history rules and says why. And `drift practices promote --block` reads when
  313. each file of the place was first committed, to pick the units most recently
  314. added there; without that history block mode is refused, and advise mode
  315. needs none.
  316. - **Drift does not commit, stage, stash, push or fetch, and it creates a branch
  317. only when a person asks.** It runs no `git` write command (`commit`, `add`,
  318. `checkout`, `reset`, `stash`, `push`, `fetch`) on your working tree or index. A
  319. hook, `drift review` or `drift init` changes files in the working tree and
  320. nothing else; what to commit is your decision. The one exception is
  321. `drift findings --branch ID`, which a person runs to turn an agent's patch into
  322. a local branch `drift/<id>`: it builds the commit through a throwaway index, so
  323. `HEAD`, your index and your working tree stay as they are, and it never pushes.
  324. ### What Drift writes, and what to commit
  325. | Path | Written by | Commit it? |
  326. | --- | --- | --- |
  327. | `.drift/conventions.yaml` | `drift init`, `drift review`, `drift practices promote` | **Yes.** The policy: proposals, decisions, modes, exceptions. CI, the Action, pre-commit and your teammates' hooks all read it. |
  328. | `drift.lock` | `drift init`; `drift review` when it promotes a withheld card or a practice; `drift practices promote` | **Yes.** Legacy violations that never block, one `<id> <path>#<symbol>` per line. Fix the code to shrink it. |
  329. | `.drift/config.yaml` | you, `drift setup` | **Yes**, so teammates and CI get the same answers (compose files that deploy nothing, Terraform ties, declared practices). |
  330. | `.drift/cache/` | every command | **No.** The fact cache and the agent session state (`.drift/cache/sessions/`). Drift writes a `.gitignore` of `*` there; a cache that git tracks is not used. |
  331. | `.drift/review-log/` | `drift review --set-log on` (opt-in) | **No.** Local only; holds its own `.gitignore` of `*`. |
  332. | `.drift/findings/` | `drift investigate` (a finding) | **No.** What an agent found: local only. Holds its own `.gitignore` of `*`; nothing posts or shares it. |
  333. | `.drift/gap-reports/` | `drift investigate` (a gap report) | **No.** A minimal example of a construct Drift does not read, with the repository's names replaced. Holds its own `.gitignore` of `*`; nothing sends it. |
  334. | `.drift/verify-cache.json` | the experimental agent verifier (`agents.verify: on` in `.drift/conventions.yaml`) | **No.** Verdicts an agent on that machine returned; Drift reads it whether or not git tracks it and gives it no `.gitignore`, so ignore it yourself. |
  335. | `.gitattributes` line `drift.lock merge=union` | you | **Yes**, see below. |
  336. A suggested `.gitignore` block. The cache, the review log, the findings and the
  337. gap reports are already covered by the `.gitignore` Drift writes inside those
  338. directories, so listing them only makes it explicit. `.drift/verify-cache.json`
  339. exists only if you turn on the experimental agent verifier, and Drift does not
  340. ignore it for you:
  341. ```gitignore
  342. # Drift: local state. Commit .drift/conventions.yaml, .drift/config.yaml and drift.lock.
  343. .drift/cache/
  344. .drift/review-log/
  345. .drift/verify-cache.json
  346. .drift/findings/
  347. .drift/gap-reports/
  348. ```
  349. Do not ignore `.drift/` as a whole: that would drop the policy that teammates
  350. and CI need. Commit after `drift review`; the Action checks the committed
  351. policy, and pre-commit stashes unstaged changes before it checks, so a
  352. `drift review` you have not staged does not count there:
  353. ```sh
  354. git add .gitattributes .drift/conventions.yaml .drift/config.yaml drift.lock && git commit -m "Accept Drift conventions"
  355. ```
  356. Agents cannot edit `.drift/` or `drift.lock`: the Claude Code hook denies those
  357. edits and, best effort, shell commands that write there. Policy is changed by
  358. people.
  359. ### Branches and merges
  360. - **`drift.lock` is one sorted entry per line**, so add `drift.lock merge=union`
  361. to `.gitattributes` (`drift init` suggests it) and parallel branches never
  362. conflict on it:
  363. ```sh
  364. echo "drift.lock merge=union" >> .gitattributes
  365. ```
  366. - **`.drift/conventions.yaml` is YAML and conflicts like any YAML file.** Resolve
  367. the markers by hand, keep both sides' decisions, then run `drift review --list`
  368. or `drift check`. A file left with conflict markers does not parse, and
  369. `drift check` stops with exit code 2 and the parse error: it is never a pass.
  370. Convention ids are stable (they do not change when the code moves), so two
  371. branches that each accepted a different proposal merge cleanly by keeping both.
  372. - **Re-running `drift init` after a merge is safe:** it keeps every decision and
  373. id and adds only new proposals.
  374. - **A change that edits the policy** (`.drift/conventions.yaml` or `drift.lock`)
  375. makes `drift check --diff-base` report every new violation, because dropping a
  376. lock entry turns that legacy violation into a new one.
  377. - **Different branches give different answers** because Drift reads the working
  378. tree: switch branches and the next run reads the new files. The cache is keyed
  379. by content, so switching is cheap.
  380. ### Checking only what a change introduces
  381. `drift check --diff-base <ref>` reports only violations introduced since the
  382. merge base of `<ref>` and `HEAD`, in changed lines and added files. It is the one
  383. flag for this: there is no `--base`, `--since` or `--diff`.
  384. ```sh
  385. drift check --diff-base origin/main
  386. ```
  387. A violation counts as introduced when its file was added, when a changed line
  388. falls inside the declaration it sits on (editing a body counts), when it is
  389. file-level and the file changed, when a renamed file did not have it before, or
  390. when a change elsewhere caused it (a deleted wrapper). Legacy violations in
  391. `drift.lock` and `drift-ignore` suppressions stay what they are. The exit code is
  392. the usual one for what is reported. A base ref that does not resolve, a missing
  393. merge base, or no git at all is exit 2, never a pass; a shallow clone says
  394. `fetch-depth: 0 needed`. `drift security --diff-base <ref>` does the same for
  395. the security inventory and always exits 0. `drift check --diff-base` works with
  396. every `--format`; `--format github` prints one annotation per violation. Details:
  397. [Drift in CI](docs/wiki/Drift-in-CI.md).
  398. Exit codes of `drift check`: 0 with nothing to fail on, 1 when a reported new
  399. violation is in block mode (any reported new violation with `--strict`), 2 on an
  400. error.
  401. ### Pre-commit and CI
  402. Pre-commit (needs `drift` on your `PATH`). The hook checks the whole working
  403. tree when a commit stages TypeScript, JavaScript or Python files; a commit that
  404. changes only `.drift/conventions.yaml` or `drift.lock` is not checked
  405. (`pre-commit run drift-check --all-files` checks it by hand):
  406. ```yaml
  407. # .pre-commit-config.yaml
  408. repos:
  409. - repo: https://github.com/dadbodgeoff/drift
  410. rev: main # pin a tag or commit
  411. hooks:
  412. - id: drift-check # or drift-check-strict
  413. ```
  414. GitHub Actions. The Action builds Drift from source with `cargo`, so the first
  415. run takes several minutes and later runs use the cache. On `pull_request` events
  416. it runs `drift check --format github --diff-base origin/<base branch>` and
  417. reports only what the pull request introduces, as annotations (`::error` for
  418. block mode, `::warning` for advice, `::notice` for suggestions) and a job
  419. summary. Every other event, `push` included, runs the full check. The job fails
  420. on new violations of conventions in block mode (`args: --strict` fails on advise
  421. mode too), and SARIF goes to code scanning. Forks get no `security-events:
  422. write`, so turn the upload off for them.
  423. ```yaml
  424. # .github/workflows/drift.yml
  425. name: Drift
  426. on:
  427. pull_request:
  428. push:
  429. branches: [main]
  430. permissions:
  431. contents: read
  432. security-events: write # only for the code scanning upload
  433. jobs:
  434. drift:
  435. runs-on: ubuntu-latest
  436. steps:
  437. - uses: actions/checkout@v5
  438. with:
  439. fetch-depth: 0 # optional: saves the Action deepening a shallow clone
  440. - uses: dadbodgeoff/drift@main # pin a tag or commit
  441. with:
  442. drift-ref: main # the Drift version to build: pin the same ref
  443. # pr-mode: "false" # check the whole repository on pull requests too
  444. # upload-sarif: "false" # private repos without GitHub Advanced Security, or PRs from forks
  445. ```
  446. ### Pull-request annotations
  447. Today, a pull request gets the annotations and job summary above. With the
  448. Action input `security: "true"` (off by default, until the shared-guard
  449. precision is measured) it also runs `drift security --diff-base`, as notices that
  450. never fail the job, and `security-comment: "true"` (needs
  451. `pull-requests: write`) posts the same text as one comment when the pull request
  452. introduces anything.
  453. `drift security --diff-base` and `drift check --diff-base` also annotate every
  454. http, server action, GraphQL or RPC entry point the change adds where Drift found
  455. no guard in what it read, or cannot tell its guard, whatever its siblings do.
  456. These are notices; they never fail the check.
  457. ### Monorepos
  458. Run `drift init` once, at the repository root. Drift finds the packages
  459. (`package.json`, `pyproject.toml`, `setup.cfg`, `setup.py` or `requirements*.txt`
  460. directories, declared by a workspace manifest or nested) and mines each in its
  461. own scope, but writes one `.drift/` at the root. `drift check`, pull-request
  462. mode, the hooks and MCP find the package of a touched file from any directory,
  463. so one policy covers every package and one `.gitattributes` line covers the lock.
  464. `drift census` lists each package with its cards, or why it is silent. To
  465. override what counts as a package:
  466. ```yaml
  467. # .drift/config.yaml
  468. packages:
  469. roots: [frontend, backend/services/*] # explicit package roots (replaces discovery)
  470. exclude: [backend/services/legacy] # not mined or checked
  471. ```
  472. ### During an agent's session
  473. With the Claude Code plugin, hooks run `drift` while the agent works: at session
  474. start (a brief and the baseline of current violations), before a write (the
  475. accepted rules for what the file declares), after an edit (new violations in that
  476. file, as facts), and at the end of the turn (blocking only on new violations of
  477. conventions in block mode). Hooks tell new violations from the ones that were
  478. there at session start, keep that baseline in `.drift/cache/sessions/`
  479. (git-ignored), and never commit anything. If a session's state is missing, the
  480. baseline is the violations in files unchanged since `HEAD`, so changed and
  481. untracked files still count. Every hook
  482. exits 0 with JSON, so a Drift failure never blocks the agent. See
  483. [Using Drift with agents](docs/wiki/Using-Drift-with-Agents.md) and the
  484. [hooks reference](docs/wiki/Hooks-Reference.md).
  485. More: [Files Drift writes](docs/wiki/Files-Drift-Writes.md),
  486. [Team rollout](docs/wiki/Team-Rollout.md),
  487. [Security and privacy](docs/wiki/Security-and-Privacy.md).
  488. ## The commands at a glance
  489. Each command's `--help` has examples. The full list of flags, outputs and exit
  490. codes is in the [command reference](docs/wiki/Command-Reference.md).
  491. | Command | What it does | Writes |
  492. | --- | --- | --- |
  493. | `drift census` | Previews the conventions Drift would propose, with evidence; `--coverage` says how much of the repository Drift maps | nothing |
  494. | `drift init` | Learns conventions, writes them as proposals, baselines legacy violations | `.drift/conventions.yaml`, `drift.lock` |
  495. | `drift review` | Accepts, blocks, sets to advise, rejects or marks exceptions; interactive without flags, where it also offers the practices that may be promoted | `.drift/conventions.yaml`, `drift.lock` when it promotes |
  496. | `drift check` | New violations of accepted conventions; `--strict`, `--diff-base`, `--format text\|json\|sarif\|github` | nothing |
  497. | `drift example FILE` | The existing file to copy from when writing new code like `FILE` | nothing |
  498. | `drift card PATH` | One file's place: entry points, guards, exposure, siblings, rules, what is not known | nothing |
  499. | `drift practices` | What the code does per concern (authn, authz, errors, logging, API, validation, config, data access, testing); `--hints` | nothing |
  500. | `drift practices promote P-ID` | Makes one practice the rule for new code in a place: an accepted convention, today's exceptions baselined; `--in`, `--with`, `--block`, `--force`, `--dry-run`, `--list`, `--json` | `.drift/conventions.yaml`, `drift.lock` (nothing with `--dry-run` or `--list`) |
  501. | `drift security` | Entry points, guards, exposure, risky operations, client leaks, env reads; `--diff-base` for a change | nothing |
  502. | `drift map` | Packages, layers, dependency graph, entry points, roles | nothing |
  503. | `drift setup` | The few questions only a person can answer; `--list`, `--json`, `--agent-brief` for agents | `.drift/config.yaml` |
  504. | `drift investigate` | Every route Drift could not settle, with the evidence; records an agent's or a person's outcome; `--json`, `--record`, `--agent-brief` | `.drift/config.yaml`; local findings and gap reports (only when recording) |
  505. | `drift findings` | What an agent found, local only; `--issue ID` an issue draft, `--branch ID` a local branch with the patch | nothing (`--write FILE`; a local branch on request) |
  506. | `drift export agents-md` / `claude-settings` | A rules block for AGENTS.md or CLAUDE.md; permission entries for read-only lookups | only with `--write` |
  507. | `drift mcp` | Serves 12 MCP tools over stdio: ten that only read, and `drift_setup_answer` and `drift_investigate_record`, which write ([MCP reference](docs/wiki/MCP-Reference.md)) | `.drift/config.yaml`, findings and gap reports, only through the two writing tools |
  508. | `drift hook claude EVENT` | The Claude Code hook handler ([hooks reference](docs/wiki/Hooks-Reference.md)) | cache and session state |
  509. | `drift scan`, `drift facts` | The fact index of the repository, or of one file | cache |
  510. Every command takes `--root <ROOT>` (default `.`) and `--no-cache`. The JSON
  511. outputs are documented in the
  512. [output reference](docs/wiki/Output-and-JSON-Reference.md). In JSON, an
  513. internet-facing entry point has `exposure` `public`; `internal` and `unknown`
  514. are written as they are.
  515. **What blocks and what only advises.**
  516. | | Proposed | Accepted (advise) | Accepted (block) |
  517. | --- | --- | --- | --- |
  518. | `drift check` | not checked | listed, exit 0 | listed, **exit 1** |
  519. | `drift check --strict` | not checked | **exit 1** | **exit 1** |
  520. | Claude Code, before writing and after an edit | nothing (block candidates included) | advice | advice, marked `(blocks)` |
  521. | Claude Code, end of turn | nothing | nothing | **blocks** (steps aside after 3 blocks or no progress) |
  522. | GitHub Action | nothing | code scanning warning (note for suggestions) | code scanning error, **job fails** |
  523. | pre-commit `drift-check` | nothing | nothing | **commit fails** |
  524. Only a person puts a convention in block mode. Default-tier conventions can
  525. block once a person sets them to; suggestions only advise unless forced
  526. (`drift review --block <id> --force`); a role of fewer than 15 members never
  527. blocks. The tiers and the release gate are explained in
  528. [Conventions and review](docs/wiki/Conventions-and-Review.md).
  529. ## Configuration at a glance
  530. Settings live in `.drift/config.yaml` (commit it). Drift reads it with defaults,
  531. so a missing file is fine. The full key list, with types, defaults and examples,
  532. is in the [configuration reference](docs/wiki/Configuration-Reference.md).
  533. | Key | Effect |
  534. | --- | --- |
  535. | `proposals: {python: off}` | Do not make Python proposals (on by default, as suggestions only) |
  536. | `packages: {roots, exclude, include}` | Override which directories are packages |
  537. | `security: {internal, public, not_deployed, terraform}` | Say what is internal or public, which deployment files deploy nothing, and which Terraform target group forwards to which code |
  538. | `practices: {authn: {...}, authz: {...}}` | Declare an instrument Drift cannot classify alone (`drift practices --hints` prints the lines) |
  539. | `setup:` | Where `drift setup` and `drift investigate` record answers and outcomes (written by the commands; do not hand-edit) |
  540. | `experimental: [...]` | Opt-in features: `wiring`, `intra_package_layering`, `test_roles`, `kind_roles` |
  541. | `agents: {brief: off}` | Turn off the session-start brief |
  542. `.drift/conventions.yaml` holds the policy; its top-level keys include
  543. `suggestion_cap: <N|all>` (how many suggestions are listed), `agents:` and
  544. `review_log:`. The environment variables Drift reads, including `DRIFT_CACHE_DIR`
  545. (move the cache) and `DRIFT_HOOK_TRACE=<file>` (append one JSON line per hook with
  546. its path and timing), are in the configuration reference.
  547. ## Using Drift with agents
  548. With `drift` on your `PATH`, install the Claude Code plugin and the MCP server:
  549. ```sh
  550. claude plugin marketplace add dadbodgeoff/drift
  551. claude plugin install drift@drift
  552. ```
  553. In a repository with `.drift/conventions.yaml`, the agent is told the accepted
  554. rules before it writes a new file, is advised after each edit that breaks one,
  555. and is stopped at the end of its turn only by conventions in block mode. **Only
  556. accepted conventions reach the agent, and an accepted suggestion only after
  557. `drift review --show-to-agents <id>`** (or when its rule family is admitted). Without the plugin, register the MCP server
  558. yourself and allow the read-only lookups:
  559. ```sh
  560. claude mcp add drift -- drift mcp
  561. ```
  562. ```sh
  563. drift export claude-settings --write .claude/settings.json
  564. ```
  565. ```sh
  566. drift export agents-md --write AGENTS.md
  567. ```
  568. The last one keeps a short generated block of accepted conventions in AGENTS.md
  569. or CLAUDE.md, ending with one rule: run `drift card <target file>` before
  570. searching for how the codebase handles auth, validation, errors, routes or data
  571. access. Agents should treat `unknown` as "Drift could not tell" and `none` as
  572. "nothing found in what Drift read", and grep for what Drift reports as not
  573. known. An agent can also go through the `drift setup` questions for you
  574. (`drift setup --agent-brief`); an answer that would make Drift say more waits as
  575. a proposal until a person confirms it. `drift investigate --agent-brief` does the
  576. same for every other open route (see "Investigate" above); the MCP tools
  577. `drift_investigate_items` (reads) and `drift_investigate_record` (writes) are its
  578. agent interface. More: [Using Drift with agents](docs/wiki/Using-Drift-with-Agents.md),
  579. [Setup questions](docs/wiki/Setup-Questions.md),
  580. [Hooks reference](docs/wiki/Hooks-Reference.md) and
  581. [MCP reference](docs/wiki/MCP-Reference.md).
  582. ## Accuracy and limits
  583. The full figures, each marked in-sample or out-of-sample with its source, are in
  584. [How accurate is it?](docs/ACCURACY.md). In short:
  585. | | In-sample (the dev repos the fixes were built on) | Out-of-sample (blind and held-out pools) |
  586. | --- | --- | --- |
  587. | TypeScript/JavaScript default tier, accepted | 100% (30/30) | **46.7% (7/15)**, Wilson 24.8–69.9% |
  588. | TypeScript/JavaScript suggestions after the show policy, accepted | – | **85.7% (6/7)**, 4 repos |
  589. | Python, everything shown, accepted (round 10) | 100% (12/12) | **50.0% (1/2)** |
  590. | Python, everything shown, accepted (the dev5-py-check) | 83.3% (25/30) | **90.9% (10/11)**, Wilson 62.3–98.4%, a blind dev pool |
  591. | Accepted cards per TypeScript/JavaScript repo | 2.69 | **0.58** (median 0) |
  592. Every label comes from blind labelling agents under rubric v3, not from real
  593. maintainers. Sources: [`eval/study/PLAN-R11.md`](eval/study/PLAN-R11.md) §1–§3,
  594. [`eval/study/runs/dev3-ts-2026-11-08/dev3-check.md`](eval/study/runs/dev3-ts-2026-11-08/dev3-check.md)
  595. and [`eval/study/runs/dev5-py/dev5-check.md`](eval/study/runs/dev5-py/dev5-check.md).
  596. - **The default tier has not passed the release gate** (≥ 95% accepted on a
  597. held-out set). No language has met it, so `drift init` proposes everything in
  598. advise mode and nothing blocks unless a person sets it to block. Review every
  599. proposal; do not accept them in bulk.
  600. - **The in-sample figures are optimistic.** Out of sample, the wrong
  601. default-tier cards were mostly scope errors: the role also holds a recurring,
  602. different kind of member that the rule should not cover. They show in the
  603. card's outliers, which is why `drift review` lists them.
  604. - **Expect few proposals:** about 1 card shown and 0.6 accepted per
  605. TypeScript/JavaScript repository out of sample; most repositories get none.
  606. - **Python proposals are suggestions only, and their evidence is small.** No
  607. Python accuracy claim is made, and no Python convention blocks unless a person
  608. forces it.
  609. - **Conventions only.** Drift checks what your code already does; it is not a
  610. linter, a type checker or a security scanner. It is a guardrail, not a
  611. security control.
  612. - **The practice map says `known` for authorization only on proof, so most
  613. routes read `unknown`.** On a 3,200-file monorepo, 19 of 137 authorization
  614. units are known and 116 unknown, 64 of them with a check that was found and is
  615. not proven; authentication reads 150 known, 20 none and 8 unknown of 178. An
  616. earlier build read 74 of the authorization units known; that included answers
  617. that were not proven, and an independent review found about 14 of 31 sampled to
  618. be false. A check Drift found but could not prove is reported as `unknown` with
  619. the reason, never as proven.
  620. - **`drift security` says `internal` only as "internal in what Drift read", on
  621. what it could read.** With a second compose
  622. stack, or Terraform or Kubernetes that Drift does not read, routes that are
  623. internal in production read internet-facing or unknown until
  624. `security.not_deployed` names what deploys nothing and `security.terraform`
  625. ties the code to its target group.
  626. - **Frameworks and constructs that are not listed or read** are in
  627. [Languages and frameworks](docs/wiki/Languages-and-Frameworks.md); a route
  628. Drift cannot list is not in the inventory, and every report ends with what it
  629. does not cover.
  630. More: [Accuracy and Limits](docs/wiki/Accuracy-and-Limits.md),
  631. [How Drift works](docs/wiki/How-Drift-Works.md) and the
  632. [Glossary](docs/wiki/Glossary.md).
  633. ## Drift Studio
  634. The Studio is a desktop app over the same CLI: it lists the proposals (block
  635. candidates first, with their outliers), lets you accept, block or reject them
  636. through `drift review`, lets you make a practice from the practice map a
  637. convention (with the same preview as `drift practices promote`), and shows violations, agent sessions, the codebase's
  638. shape and its security inventory. It is not packaged yet: run it from a checkout
  639. of this repository, with `drift` on your `PATH` (or chosen in its Settings):
  640. ```sh
  641. npm ci
  642. ```
  643. ```sh
  644. npm run start -w drift-studio # build and open the desktop app
  645. ```
  646. ```sh
  647. npm run dev -w drift-studio # the renderer in a browser, on fixtures
  648. ```
  649. Nothing is sent anywhere. Details: [apps/studio/README.md](apps/studio/README.md).
  650. ## Design and safety
  651. ```
  652. files -> ingest -> language parser (oxc, ruff) -> facts -> mining -> conventions
  653. -> review -> conventions.yaml + drift.lock -> check -> CLI / hooks / CI
  654. ```
  655. | Crate | Role |
  656. | --- | --- |
  657. | `drift-core` | Language-neutral fact model, safe ingest, content-addressed fact cache |
  658. | `drift-ts` | TypeScript/JavaScript parser on oxc, module resolution, framework adapters |
  659. | `drift-py` | Python parser on ruff, import resolution, framework adapters ([details](docs/v2/PYTHON.md)) |
  660. | `drift-mine` | Roles, convention mining, policy, lock and check (language-neutral) |
  661. | `drift-cli` | The `drift` binary |
  662. - **Deterministic.** Output is byte-identical across runs, thread counts,
  663. operating systems and checkout paths, and this is tested.
  664. - **Safe on hostile repos.** Drift never follows symlinks out of the repo, never
  665. runs repo scripts, skips files over 1 MB, and skips generated and minified
  666. code. It writes nothing through a symbolic link that leaves the repo: such a
  667. link at `.drift/conventions.yaml`, `drift.lock` or an export target is refused
  668. (exit 2), and a fact cache with a link in it is not used. A fact cache that git
  669. tracks is not used either, so committed facts cannot hide a violation; the
  670. GitHub Action also uses a fresh cache outside the checkout.
  671. - **Bounded memory.** Each file is parsed in its own arena and freed once it is
  672. turned into facts. Facts are cached by content hash.
  673. - **No network, no telemetry.** Drift makes no network call and has no
  674. telemetry. See [Security and privacy](docs/wiki/Security-and-Privacy.md) and
  675. [SECURITY.md](SECURITY.md).
  676. The pipeline, the cache and what "proven" means are in
  677. [How Drift works](docs/wiki/How-Drift-Works.md).
  678. ## Contributing, support and license
  679. - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) lists the gates CI runs
  680. (`scripts/gates.sh` runs them locally). Releases are made only in CI:
  681. [RELEASING.md](RELEASING.md).
  682. - **Support:** open an issue on the GitHub repository. Report a vulnerability
  683. privately through the repository's Security tab, as [SECURITY.md](SECURITY.md)
  684. says; do not open a public issue.
  685. - **Upgrading and compatibility:**
  686. [Versioning and upgrades](docs/wiki/Versioning-and-Upgrades.md) and the
  687. [beta release notes](docs/RELEASE-NOTES-beta.md).
  688. - **License:** [Apache-2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.