Drift

Your agent is about to build it twice. Drift tells it first.

/plugin marketplace add mick-gsk/drift
/plugin install drift@drift

_{Not a mock-up — bash demos/guard-in-30-seconds.sh runs exactly this on your machine, in under a second.}

Restart Claude Code, then run /drift:doctor — it checks the install and, from the index it just built, names what is already defined twice in your repository:

[x] index holds 1128 file(s)

5 name(s) already defined in more than one place:
  - _finding_key: scripts/ecosystem_check.py, scripts/triage_findings.py, src/drift/incremental.py

Those two lines are the whole install: the guard imports nothing but the standard library and runs from the plugin itself, so there is no pip install, no dependency to resolve and nothing to configure. It writes nothing into your repositories — the index lives in your cache (~/.cache/drift), keyed by repository path, because a plugin that fires in every project you open has no business leaving a directory in each of them. A project that wants the index alongside its source opts in by creating a .drift/ directory.

Eight file types in one index — Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin and C# (.py .ts .tsx .js .jsx .mjs .cjs .go .rs .java .kt .kts .cs), in one index — a name defined in Python is found from TypeScript, because validate_token, validateToken and ValidateToken all normalise to the same thing. Other languages pass through untouched.

GitHub Actions is paused on this account, so there is no CI badge to show and pull requests will not get an automated run. That is a billing state, not a verdict on the code: the suite is green locally, and make check runs the same lint, types, tests and self-analysis CI would. Contributions are welcome as usual — say so in the PR and the checks get run by hand.

Docs · Quick Start · Playground · Benchmarking · Trust & Limitations · Community

Using AI coding tools? Start here · CI & team rollout? Team rollout guide · Benchmarks & evidence? Study

After every edit your agent makes, drift says one of two things — or, most of the time, nothing at all:

drift:
  - `validate_token` already exists in src/auth/tokens.py:44
  - first import from src/api/ into src/db/ anywhere in this repository

That is the whole surface. Two questions, asked of a SQLite index of your repository, answered before the agent writes its next line:

1. Does this symbol already exist somewhere else? Names are normalised and signatures hashed, so validateToken and validate_token(token, audience) still match.
2. Has this directory ever imported from that one? Boundaries are observed, not configured — the index records which directory-to-directory imports your repository actually contains, so a first-ever crossing stands out without you writing a single rule.

/drift:stats shows what it caught this session.

Replaying every file of five real repositories through the same lookups the hook runs, as if each had just been written:

Reproduce it with python scripts/gates/measure_noise.py <dir-of-checkouts>.

The first run of that measurement said 27–69 %, and what it reported was junk: config, argv, add, plus fastapi's docs_src/ tutorials, which define Item in over a hundred files on purpose. Nothing in the test suite could have caught it — the fixture is six files written to demonstrate the two signals. Five rules came out of that measurement, each one a defect it exposed: a function does not duplicate a class, a name repeated across the codebase is a convention rather than an accident, short and dunder names carry no evidence, test and example directories restate names by design, and a TypeScript const counts only when it holds a function — Python never indexed plain assignments, and the asymmetry was the single largest source of noise.

What survives is worth reading: _make_timedelta really is defined twice in Flask, and Blueprint really does exist in both blueprints.py and sansio/blueprints.py.

Asked to write a function that already existed elsewhere, with the guard installed and no other instruction, Claude came back with this on its own:

Created src/api/schemas.py:1 with just that function.

One thing worth flagging: the drift guard reports a validate_token already exists at src/auth/tokens.py:4. I didn't look at it, per your instruction — so I don't know whether it's a real implementation this one now shadows. Worth a check before anything imports the new one.

Nobody asked it to check for duplicates. The guard put the fact in front of it, and it did the rest. One run, unedited.

Off by default. /drift:amphetamin on turns it on for a repository.

Agents stop early far more often than they work slowly, and most early stops leave something on the table. While the mode is on, the Stop hook refuses one stop per session — and only when drift's index recorded a symbol introduced during that session which already existed elsewhere. It hands back a specific, finishable instruction and never asks twice:

{"decision": "block",
 "reason": "drift recorded 1 symbol(s) introduced in this session that already
            existed elsewhere in this repository. Before finishing, for each
            one: reuse the existing definition, or state in one line why a
            second definition belongs here."}

That criterion is a recorded fact, not a judgement about whether an answer felt finished, so it cannot fire on a session that left nothing behind.

What is a mechanism and what is not. The held stop is a mechanism: it fires or it does not, and there are tests for both. The mode also injects four throughput instructions at session start — batch independent tool calls, do not re-read unchanged files, prefer ranged reads, keep going while the next step is determined. Those are instructions. Nothing enforces them, and no speedup has been measured; calling them a guarantee would be the same mistake as citing a benchmark nobody ran.

What it will not do. It does not skip permission prompts, truncate reads, shorten plans, skip verification or lower any threshold. An earlier draft auto-approved read-only tools at the permission prompt; that was cut. The prompt on Read is your only view of what an agent reaches for, and repository content is an established prompt-injection surface — an agent steered by a file it just read can ask for ~/.ssh/id_rsa. A public plugin that removes that prompt trades a real control for convenience. A test fails if the mechanism ever grows back.

The guard is a separate module that imports nothing but sqlite3, ast and json — no click, no rich, no ML stack, nothing from the analysis engine. That constraint is enforced by a test, not by intention.

The whole hook, as Claude Code runs it — shell start, git rev-parse, the lookup — against an index of 2169 files:

Cold, macOS/arm64, Python 3.12. The reference rows come from guard_baseline.json; the two hook rows are the round trip a session actually pays, which is a fairer number than the Python call on its own. Clean checkout to a working guard: 5 s (bash scripts/gates/measure_install.sh).

If the guard breaks, it stays silent and the session continues — it can report, but it can never block.

The plugin is the front door; the same engine has a full command line for CI, reports and one-off analysis.

uvx drift-analyzer analyze --repo .

One command. No pre-install. Results in under a minute on a typical repo. No config needed — drift analyze auto-detects the right profile. drift init --auto saves it to drift.yaml without prompts (vibe-coding / default / strict).

drift status → repo-level score (0–1 · 🟢/🟡/🔴) · drift analyze → per-finding detail (INFO/LOW/MEDIUM/HIGH). Bare drift runs drift status.

Drift measures what your linter cannot: cross-file structural coherence — the layer where pattern fragmentation, boundary violations, and duplicate divergence accumulate across commits. 24 signals · deterministic, no LLM in detection · runs locally, offline · evidence & limitations

🌐 No install at all? Analyze any public repo in your browser → · Interactive code playground →

Recommended install: pipx install drift-analyzer (isolated CLI) · Python 3.11+ · also via pip, Homebrew, Docker, GitHub Action, pre-commit → · best fit for Python repos with 20+ files; TypeScript/TSX: pip install 'drift-analyzer[typescript]'

Most linters catch single-file style issues. Drift catches what they miss: cross-file structural drift that accumulates silently — in any codebase, at any scale.

🔍 Before — drift brief analyses your repo scope and generates structural constraints ready to paste into your agent prompt 🚦 After — drift check runs 20+ cross-file signals and exits 1 on violations — CI, SARIF, and pre-commit ready 🧠 Over time — Adaptive calibration reweights signals via feedback, git outcome correlation, and GitHub label correlation 📚 Negative context library — drift_nudge delivers structured anti-patterns (canonical alternatives + CWE tags) directly into your agent's context — no manual guardrail writing needed

One page, three milestones — enough to go from first run to measurable improvement.

Which profile? AI-heavy codebase → drift init -p vibe-coding. Unsure → drift init (default). You can switch later.

Before a session — generate guardrails:

drift brief --task "refactor the auth service" --format markdown
# → paste output into your agent prompt before delegation

After a session — enforce structure:

drift check --fail-on high         # local or CI gate
drift check --fail-on none         # pre-commit hook (advisory, report-only)
drift analyze --repo . --format json  # full report
drift adr --repo .                 # list active ADRs and their relevance to scope

📖 Full workflow guide →

Drift findings use short codes. Here are the five you'll see most often:

Every finding includes a human-readable reason and a concrete next_action. Full reference: all 24 signals →

For GitHub Copilot coding agent (issue-assigned autonomous PRs), use the Copilot Coding Agent Task issue template and keep required task-brief sections complete. See CONTRIBUTING.md.

Start here (no MCP needed): drift kit init → /drift-fix-plan in VS Code Copilot Chat. Full CI + MCP: drift init --mcp --ci --hooks. Language support: Python (full) · TypeScript/TSX 17/24 via pip install 'drift-analyzer[typescript]' · language matrix

# Try it — add this to .github/workflows/drift.yml
name: Drift
on: [push, pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    permissions:
      security-events: write   # for SARIF upload
      pull-requests: write     # for PR comments
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0       # full history for temporal signals
      - uses: mick-gsk/drift@v2
        with:
          fail-on: none        # report-only — tighten once you trust the output
          upload-sarif: "true" # findings appear as PR annotations
          comment: "true"      # summary comment on each PR

Outputs available for downstream steps: drift-score, grade, severity, finding-count, badge-svg

drift kit init (once per repo) scaffolds prompt files for VS Code Copilot Chat. After drift analyze, drift writes .vscode/drift-session.json and shows a Copilot Chat Handoff panel in the terminal. Open VS Code Copilot Chat and call:

One-time setup — one command:

drift kit init   # scaffolds prompt files + VS Code settings — run once per repo

No additional Drift-specific extension install is needed for this workflow; you still need VS Code with GitHub Copilot Chat installed/enabled. drift kit init creates .github/prompts/ with all four prompt files and merges chat.promptFilesLocations into .vscode/settings.json without touching your existing keys. Idempotent — safe to re-run.

📖 VS Code Copilot Chat Workflow guide →

This is the advanced path. MCP is valuable for active agent loops with deterministic tool contracts — but it adds setup friction and consumes model context budget. Start with the Copilot Chat path above if you haven't already.

Cursor, Claude Code, and Copilot call drift directly via MCP server — the agent runs a full session loop:

The execution core (brief, nudge, diff, fix-plan, feedback) covers most agent loops. The full tool surface is documented in integrations →.

VS Code — add to .vscode/mcp.json:

{
  "servers": {
    "drift": {
      "type": "stdio",
      "command": "drift",
      "args": ["mcp", "--serve"]
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "drift": {
      "command": "drift",
      "args": ["mcp", "--serve"]
    }
  }
}

Cursor — add to .cursor/mcp.json:

{
  "mcpServers": {
    "drift": {
      "type": "stdio",
      "command": "drift",
      "args": ["mcp", "--serve"]
    }
  }
}

Or auto-generate: pip install drift-analyzer[mcp] && drift init --mcp

📖 MCP setup guide →

pre-commit: Add drift diff --staged-only as a hook — findings block the commit before they reach CI.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/mick-gsk/drift-pre-commit
    rev: v1.0.0
    hooks:
      - id: drift-check

📖 Full integration guide → · drift-pre-commit repo →

Pick a profile that matches your project — or start with default and calibrate later:

Team tip: Commit drift.yaml → CI enforces the same thresholds. Inspect with drift config show --repo ..

📖 Profile gallery with full details → · Configuration reference →

Drift is most useful when you track score deltas, not snapshots.

Day 0 — capture your baseline:

drift analyze --repo . --format json > baseline.json
# note the composite score, e.g. 12.5

Ongoing — ratchet the threshold down:

# drift.yaml — tighten after each successful sprint
thresholds:
  fail_on: high          # block high-severity findings
  max_score: 10.0        # lower this as your score improves

Weekly — track the trend:

drift trend              # shows score evolution over recent commits

Example outcome: "Score dropped from 12.5 → 8.3 in 4 weeks — 3 PFS and 1 AVS finding resolved, CI gate tightened from 12.0 to 9.0." The GitHub Action exposes drift-score as a step output — pipe it to a dashboard or Slack webhook.

From Ruff / pylint: Drift operates one layer above single-file style. It detects when AI generates the same error handler four different ways across modules — something no linter sees.

From Semgrep / CodeQL: Semgrep finds known vulnerability patterns in single files. Drift finds structural erosion across files — pattern fragmentation, layer violations, temporal volatility — that security scanners don't target. Semgrep Pro Engine adds cross-file dataflow analysis for security — drift adds cross-file structural coherence analysis for architecture. Different questions.

From SonarQube: Drift runs locally with zero server setup and produces deterministic, reproducible findings per signal. Add it alongside SonarQube — not instead. See drift vs SonarQube for the detailed comparison.

From GitHub Copilot Code Review: Copilot Review checks the PR after the code is written. Drift operates before (drift brief generates guardrails before an agent task starts) and during (drift nudge gives directional feedback inside the editing session). Use both — different positions in the workflow.

From jscpd / CPD: Drift's duplicate detection is AST-level, not text-level. It finds near-duplicates that text diff misses and places them in architectural context.

✔ = within primary design scope · — = not a primary design target · Partial = limited coverage

¹ Via drift-analyzer[typescript]. 17/24 signals supported via tree-sitter. Python is the primary analysis target.

Comparison reflects primary design scope per STUDY.md §9. This table was authored by the maintainer and has not been independently verified. Corrections welcome via discussion.

Show your repo's drift score with a shields.io badge:

drift badge                    # prints URL + Markdown snippet
drift badge --format svg -o badge.svg  # self-contained SVG

Paste the Markdown output into your README:

[![Drift Score](https://img.shields.io/badge/drift%20score-0.41%20(C)-yellow?style=flat)](https://github.com/mick-gsk/drift)

Automate in CI: The GitHub Action exposes a badge-svg output — pipe it into your repo or a dashboard.

git fetch --unshallow

python -m jsonschema -i drift.yaml drift.schema.json   # requires pip install jsonschema

which drift          # macOS/Linux
where drift          # Windows
python -m drift analyze --repo .   # always works regardless of PATH

Drift's biggest blind spots are found by people running it on codebases the maintainers have never seen. A well-documented false positive can be more valuable than a new feature.

git clone https://github.com/mick-gsk/drift.git && cd drift && make install
make test-fast

See CONTRIBUTING.md · ROADMAP.md

Drift's pipeline is deterministic and benchmark artifacts are published in the repository — claims can be inspected, not just trusted.

¹ Upper-bound estimate from the historical v0.5 6-signal model on a score-weighted, single-rater sample — not yet revalidated for the current 24-signal model. See STUDY.md §5. ² Single uncontrolled run — see RESEARCH.md H4/H5 for what a controlled study would require.

• No LLM in detection. The deterministic core uses no LLM inference — same input, same output. Optional local embeddings (pip install drift-analyzer[embeddings]) improve near-duplicate detection but are not required and do not call external services.
• Single-rater caveat: ground-truth classification is not yet independently replicated.
• Small-repo noise: repositories with few files can produce noisy scores. Calibration mitigates but does not eliminate this.
• Temporal signals depend on clone depth and git history quality.
• The composite score is orientation, not a verdict. Interpret deltas via drift trend, not isolated snapshots.
• Own score context: Drift's self-score is driven primarily by architecture violations and explainability deficit (undocumented internal functions). Pattern fragmentation in modules with intentionally diverse error-handling contracts (signals, API, calibration, integrations) is suppressed via path_overrides — those variations are architectural, not accidental. The score reflects a fast-moving codebase that prioritises signal correctness over internal documentation. The published figure covers src/drift; the whole repository, tests and tooling included, scores 0.619. See drift_self.json for the breakdown and the exact scope string.
• Signal overlap: Some signals measure related phenomena (e.g., MDS and PFS both detect code similarity; CCC and TVS both use git history). A formal inter-signal correlation analysis has not been conducted. Overlap does not produce double-counting in the composite score (each signal contributes independently), but it means some findings may describe the same underlying issue from different angles.
• Weight derivation: Default signal weights for the 6 original signals were derived via rank-correlation (Kendall's τ) against manual architectural assessments on 5 open-source repos (single rater). Weights for the 18 newer signals are conservative heuristic assignments pending broader validation. Full methodology: STUDY.md §1, scoring model.

Full methodology: Benchmarking & Trust · Full Study · Open Research Questions

Drift detects architectural erosion: structural patterns that accumulate silently across many commits and that static analysis, linters, and type checkers cannot see because they only look at individual files in isolation.

Specifically, drift detects:

• Erosion — pattern fragmentation, mutant duplicates, diverging implementations accumulating across commits
• Responsibility mixing — imports crossing declared layer boundaries
• Risky change structures — churn hotspots, temporal coupling, high-churn complexity

Drift does not determine whether your architecture is good. It measures whether it is changing in structurally risky ways.

Drift is NOT a replacement for:

What drift adds on top of those tools: It detects whether the structure of your codebase is drifting away from its intended architecture — specifically the patterns that emerge from AI-assisted development (Cursor, Copilot, Claude) when no human has reviewed the cumulative effect of 50+ small PRs.

Primary target: teams and solo developers using AI coding tools (Cursor, GitHub Copilot, Claude Code) where agent-generated code accumulates faster than architectural review can keep up.

Drift is maintained by Mick Gottschalk as an independent open-source project.

• License: MIT — fork-safe, vendor-lock-free, reproducible CI.
• Bus factor mitigation: All signals, benchmarks, and release automation are fully documented and reproducible without the maintainer. The project has zero external service dependencies for core analysis.
• Funding: Currently unfunded. If your team relies on drift, consider sponsoring to support continued development.
• Response target: First reply within 72 hours on issues and discussions.

MIT. See LICENSE.