---

What it actually says

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. Silence is the normal case,
not a failure.

What that looks like in a real session

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.

Why it can run inside the loop

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.

Measured on this repository (344 Python files)	p50	p95
Before an edit to a new file	70 ms	72 ms
After an edit to an existing file	86 ms	87 ms
Python interpreter startup alone, for reference	24 ms	29 ms
import drift.cli, the path the guard avoids	3229 ms	3959 ms

20 runs each, cold, macOS/arm64, Python 3.12 → guard_baseline.json.
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 CLI

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]'

[!NOTE]
Drift eats its own dog food. Drift runs drift self on its own source and publishes the result: drift_self.json carries the score, the grade and the per-signal breakdown, and the badge above is generated from it. The number lives in that one file rather than being repeated here, so it cannot go stale in prose. Precision/Recall details in Trust & Limitations.

---

🤔 Why drift?

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.

Without Drift	With Drift
Agent duplicates a helper in 3 modules — tests pass Layer boundary violated in a refactor — CI green Auth middleware reimplemented 4 ways — linter silent Score degrades over weeks — nobody notices	drift brief injects structural guardrails before the agent writes code drift nudge flags new violations in real-time during the session drift check blocks the commit on high-severity findings drift trend tracks score evolution — regressions are visible

🔍 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

---

👤 Who is drift for?

Audience	Starting point	You'll use
Developers using AI tools (Copilot, Cursor, Claude)	drift setup → drift status	brief, nudge, check — catch what your agent breaks
Tech leads & teams adopting AI at scale	Team Rollout Guide	CI gate, SARIF, trend — enforce structural standards
Solo developers wanting structural quality	drift analyze --repo .	fix-plan, explain — find and fix erosion patterns

---

📅 30-day adoption plan

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

Week	Goal	Commands	Done when
1 — Baseline	See your starting point	drift setup → drift analyze --repo . --format json > baseline.json	You have a score and a saved baseline file
2 — Understand	Triage the top 5 findings	drift status · drift explain <signal>	Each finding is marked fix, ignore, or defer
3–4 — Improve	Fix findings, block regressions	drift check --fail-on high (CI or pre-push) · drift trend	Score is lower than baseline; CI gate is green

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 →

Signals at a glance

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

Code	Signal	What it catches	Example
PFS	Pattern Fragmentation	Same pattern reimplemented inconsistently across modules	3 different parse_config() helpers
MDS	Mutant Duplicate	Near-duplicate functions that diverged over time	Two validate_input() with subtle differences
AVS	Architecture Violation	Imports that cross declared layer boundaries	api/ importing directly from db/
BAT	Bypass Accumulation	Growing # noqa, type: ignore, pragma bypasses	40 suppressions added in one sprint
TPD	Test Polarity Deficit	Missing negative / error-path test coverage	Only happy-path tests for auth module

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

---

🔌 Works with

Copilot Chat	CI/CD	Git Hooks	Install	MCP (advanced)
/drift-fix-plan · /drift-export-report · /drift-auto-fix-loop	GitHub Actions · SARIF	pre-commit · pre-push	pip · pipx · uvx · Homebrew · Docker	Cursor · Claude Code · Copilot

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

GitHub Actions

# 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

VS Code Copilot Chat — no MCP needed

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:

Slash command	What it does
/drift-fix-plan	Prioritized repair tasks from the latest findings
/drift-export-report	Self-contained findings report as Markdown
/drift-auto-fix-loop	Step through findings one-at-a-time with confirm/skip gates

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 →

MCP / AI Tools — advanced execution layer

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:

Phase	MCP Tool	What it does
Plan	drift_brief	Scope-aware guardrails injected into the agent prompt
Code	drift_nudge	Real-time safe_to_commit check after each edit
Verify	drift_diff	Full before/after comparison before push
Learn	drift_feedback	Mark findings as TP/FP — calibrates signal weights

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

Copy-paste MCP config

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 →

---

🎛️ Configuration profiles

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

Profile	Best for	Command
default	Most projects	drift init
vibe-coding	AI-heavy codebases (Copilot, Cursor, Claude)	drift init -p vibe-coding
strict	Mature projects, zero tolerance	drift init -p strict
fastapi	Web APIs with router/service/DB layers	drift init -p fastapi
library	Reusable PyPI packages	drift init -p library
monorepo	Multi-package repos	drift init -p monorepo
quick	First exploration, demos	drift init -p quick

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

📖 Profile gallery with full details → · Configuration reference →

---

📈 Measuring improvement — baseline and ratchet

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.

---

Advanced: Adaptive learning, Negative context library, Guided mode

Adaptive learning & calibration

Drift does not treat all signals equally forever. It maintains a per-repo profile:

• Adaptive calibration engine uses precision-weighted linear interpolation across three evidence sources: explicit drift feedback mark, git outcome correlation, and GitHub issue/PR label correlation. As feedback accumulates, observed signal precision gradually overrides default weights (see calibration design).
• Feedback events are stored as structured FeedbackEvent records and can be reloaded and replayed across versions (record_feedback, load_feedback).
• Profile builder (build_profile) produces a calibrated weight profile that drift check and drift brief use to focus on the most trusted signals in your codebase.

CLI surface: drift feedback, drift calibrate, drift precision (for your own ground-truth checks).

Negative context library for agents

Drift can turn findings into a structured "what NOT to do" library for coding agents:

• Per-signal generators map each signal (PFS, MDS, AVS, BEM, TPD, …) to one or more NegativeContext items with category, scope, rationale, and confidence.
• Anti-pattern IDs like neg-MDS-… are deterministic and stable — ideal for referencing in policies and prompts.
• Forbidden vs. canonical patterns: each item includes a concrete anti-pattern code block and a canonical alternative, often tagged with CWE and FMEA RPN.
• Security-aware: mappings for MISSING_AUTHORIZATION, HARDCODED_SECRET, and INSECURE_DEFAULT generate explicit security guardrails for agents.

API: findings_to_negative_context() and negative_context_to_dict() deliver agent-consumable JSON for drift_nudge, drift brief, and other tools.

Guided mode for vibe-coding teams

If your team ships most changes via AI coding tools (Copilot, Cursor, Claude), drift includes a guided mode:

• CLI guide: drift start prints the three-command journey for new users: analyze → fix-plan → check with safe defaults.
• Vibe-coding playbook: examples/vibe-coding/README.md documents a 30-day rollout plan (IDE → commit → PR → merge → trend) with concrete scripts and metrics.
• Problem-to-signal map: maps typical vibe-coding issues (duplicate helpers, boundary erosion, happy-path-only tests, type-ignore buildup) directly to signals like MDS, PFS, AVS, TPD, BAT, CIR, CCC.
• Baseline + ratchet: ready-made drift.yaml, CI gate, pre-push hook and weekly scripts implement a ratcheting quality gate over time.

📖 Start here if you are a heavy AI-coding user: Vibe-coding technical debt solution →

---

🔄 Coming from another tool?

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.

Capability comparison

Capability	drift	SonarQube	Ruff / pylint / mypy	Semgrep / CodeQL	jscpd / CPD
Pattern Fragmentation across modules	✔	—	—	—	—
Near-Duplicate Detection (AST-level)	✔	Partial (text)	—	—	✔ (text)
Architecture Violation signals	✔	Partial	—	Partial (custom rules)	—
Temporal / change-history signals	✔	—	—	—	—
GitHub Code Scanning via SARIF	✔	✔	—	✔	—
Adaptive per-repo calibration	✔	—	—	—	—
MCP server for AI agents	✔	—	—	—	—
Zero server setup	✔	—	✔	✔	✔
TypeScript support	Partial ¹	✔	—	✔	✔

✔ = 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.

---

🏷️ Add a drift badge to your README

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.

---

📚 Documentation

Topic	Description
Quick Start	Install → first findings in 2 minutes
Brief & Guardrails	Pre-task agent workflow
CI Integration	GitHub Action, SARIF, pre-commit, progressive rollout
Signal Reference	All 25 signals with detection logic
Benchmarking & Trust	Precision/Recall, methodology, artifacts
MCP & AI Tools	Cursor, Claude Code, Copilot, HTTP API
Configuration	drift.yaml, layer boundaries, signal weights
Configuration Levels	Zero-Config → Preset → YAML → Calibration → MCP → CI
Calibration & Feedback	Adaptive signal reweighting, feedback workflow
ADR Inspection (drift adr)	List active ADRs from docs/decisions/ — filter by task or scope
Vibe-coding Playbook	30-day rollout guide for AI-heavy teams
Open Research Questions	5 falsifiable hypotheses on validity and effectiveness
Contributing	Dev setup, FP/FN reporting, signal development

---

🛠 Troubleshooting

No Python files found

drift walks the repo starting from the path passed to --repo. If the path is wrong or the repo uses a non-standard layout, use --repo /absolute/path/to/project and verify via drift analyze --repo . --format json | python -m json.tool | Select-String files.

Shallow clone — git signals are missing or unreliable

Time-based and co-change signals (TVS, CCC, AVS) require full git history. Unshallow the clone:

git fetch --unshallow

In CI (GitHub Actions), add fetch-depth: 0 to your actions/checkout step.

drift.yaml schema validation failed

Validate your config against the schema:

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

Or regenerate a fresh config: drift init (overwrites drift.yaml with safe defaults).

drift: command not found after install

The drift binary may not be on your PATH. Check:

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

If you installed with pip install --user, add ~/.local/bin (Linux/macOS) or %APPDATA%\Python\Scripts (Windows) to your PATH.

---

🤝 Contributing

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.

I want to…	Go here
Ask a usage question	Discussions
Report a false positive / false negative	FP/FN template
Report a bug	Bug report
Suggest a feature	Feature request
Propose a contribution before coding	Contribution proposal
Report a security vulnerability	SECURITY.md — not a public issue

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

See CONTRIBUTING.md · ROADMAP.md

---

🔒 Trust and limitations

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

Metric	Value	Artifact
Wild-repo precision ¹	77 % strict / 95 % lenient (5 repos)	study §5
Ground-truth regression	0 FP, 0 FN (84 TP, 206 fixtures)	v2.51.1 baseline
Mutation recall	75 % (75/100 injected)	mutation benchmark
Agent session score delta	0.495→0.506 (1 live run) ²	Copilot Autopilot artefacts

¹ 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

---

� What drift is — and what it is not

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:

Tool	What it does	Why drift doesn't replace it
ruff / flake8 / pylint	Style, syntax, import order, per-file lint rules	Drift does not enforce code style. Run your linter as-is.
mypy / pyright	Type correctness	Drift does not check types.
Semgrep / Bandit	Security vulnerability patterns, taint analysis	Drift does not scan for CVEs or injection vectors.
SonarQube / SonarLint	Code quality metrics, duplication, test coverage gaps	Drift measures cross-file structural coherence, not coverage or per-function quality.
pytest / coverage.py	Test execution and coverage measurement	Drift does not run tests.

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.

---

�🔧 Sustainability

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.

---

⭐ Star History

---

📄 License

MIT. See LICENSE.