| name | drift-cli |
| description | Use whenever writing or editing an AGENTS.md or when `drift` / `drift check` are the cause of a failed check |
Bind docs to code and check for drift.
Any markdown file in your repo can declare anchors to code — specific files or AST symbols. When bound code changes, drift check flags the doc as stale. Agents that change code must update the docs they affect.
Usage
Write a markdown doc, then bind it to code:
drift link docs/auth.md src/auth/login.ts
drift link docs/auth.md src/auth/provider.ts#AuthConfig
drift link writes the binding to drift.lock at the repo root and stamps a content signature — an AST fingerprint of the target file or symbol. It hashes what's on disk, so uncommitted files work fine. You can also reference code inline — @./src/auth/provider.ts#AuthConfig in the doc body — and drift link will stamp those too.
Check if docs are fresh:
drift check
Refresh all anchors in a doc after updating it:
drift link docs/auth.md
What a doc anchor looks like
After linking, bindings live in drift.lock at the repo root:
docs/auth.md -> src/auth/login.ts sig:e4f8a2c10b3d7890
docs/auth.md -> src/auth/provider.ts#AuthConfig sig:1a2b3c4d5e6f7890
You can also use inline references in the doc body — @./src/auth/provider.ts#AuthConfig — and drift link will stamp those in the lockfile too.
Every anchor has three parts:
src/auth/provider.ts #AuthConfig sig:1a2b3c4d5e6f7890
└── file path ──────┘ └─ symbol ─┘ └──── signature ────┘
- Path — the file you're binding to, relative to the repo root.
- Symbol — optional
#Name suffix that narrows the anchor to a specific declaration (function, class, type). Only changes to that symbol trigger staleness.
- Signature — content fingerprint stamped by
drift link. An XxHash3 hash of the file or symbol's normalized AST, so staleness detection doesn't depend on VCS history. Rebasing, amending, or linking uncommitted files all work. Per-anchor, so different files track independently.
Cross-repo docs (origin)
Docs that travel across repo boundaries — installed skills, vendored docs, shared templates — can declare where their anchors belong via a trailing origin: field:
docs/skill.md -> src/main.zig sig:a1b2c3d4e5f67890 origin:github:fiberplane/drift
When origin doesn't match the current repo, drift check skips those anchors instead of reporting false "file not found" errors. Anchors without origin are always checked.
Commands
drift check Check all docs for staleness (exits 1 if stale)
drift status Show all doc anchors from drift.lock
drift link Add or refresh bindings in drift.lock
drift unlink Remove a binding from drift.lock
drift refs Reverse lookup — which docs reference a given file
drift lint is an alias for drift check.
How staleness works
Each anchor's sig: field records a fingerprint of the code at the time it was linked. drift check recomputes the fingerprint from the current file and compares. For supported languages (TypeScript, Python, Rust, Go, Zig, Java), comparison is syntax-aware — drift parses with tree-sitter and hashes a normalized AST fingerprint (node kinds + token text, no whitespace or position data). Reformatting won't trigger false positives. Symbol-level anchors (#AuthConfig) narrow this to just that declaration's subtree. Unsupported languages fall back to raw content comparison.
No VCS history is needed for staleness detection — drift check works entirely from the stored signature and current file content.
$ drift check
docs/auth.md
STALE src/auth/provider.ts#AuthConfig (changed after doc)
changed by mike in e4f8a2c (Mar 15)
"refactor: split auth config into separate concerns"
STALE src/core/old-module.ts (file not found)
ok src/auth/login.ts
docs/payments.md
ok
1 doc stale, 1 ok
CI
drift check exits 1 when any doc is stale, so it works as a CI gate:
name: Drift
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: fiberplane/drift@main
- run: drift check
For faster CI runs, use --changed to scope checking to docs affected by the files that changed in the PR:
- run: drift check --changed src/auth
fetch-depth: 0 is recommended — drift uses VCS history for blame info on stale anchors. With sig: provenance (the default), staleness detection itself doesn't need history. The setup action auto-detects platform, downloads the right binary from GitHub releases, and verifies its checksum before installing.
