Quick Start¶
Repo:
mick-gsk/drift· Package:drift-analyzer· Command:drift
You want to try drift? Good — you'll have your first findings in two minutes.
If you want to see what drift catches before you install it, check out Problems Every Vibe-Coder Recognizes — real code examples from AI-assisted projects.
0. Before you start¶
Drift requires Python 3.11+. If your shell or CI runner is still on 3.10, fix that first — you want the first run to be a signal test, not an environment fight.
1. Install¶
One command to get started
Not sure where to begin? Run drift setup — it asks 3 questions and writes
a tuned config file for your project type.
Shortcut
Bare drift (no subcommand) runs drift status automatically — your daily health check in one word.
No project handy? Try on FastAPI
Real findings on a real codebase — no setup, no risk.2. Set up and check health¶
cd /path/to/your/project
drift setup # 3-question wizard: personalised config
drift status # traffic-light health check
Two views, same data
drift status shows a repo-level score (0–1 → 🟢 GREEN < 0.35, 🟡 YELLOW, 🔴 RED ≥ 0.65). Quick health check.
drift analyze shows per-finding severity (INFO / LOW / MEDIUM / HIGH / CRITICAL). Use for triage.
Both use the same data — different lenses.
drift status gives you a traffic-light summary with plain-language explanations and copy-paste prompts for your AI assistant.
3. Dive into full findings¶
4. Turn findings into repair tasks¶
fix-plan turns your top findings into concrete, ordered tasks with constraints and success criteria.
5. What you'll see¶
Here's what a typical first run looks like:
╭─ drift analyze myproject/ ──────────────────────────────────────────────────╮
│ DRIFT SCORE 0.52 │ 87 files │ 412 functions │ AI: 34% │ 2.1s │
╰──────────────────────────────────────────────────────────────────────────────╯
┌──┬────────┬───────┬──────────────────────────────────────┬──────────────────────┐
│ │ Signal │ Score │ Title │ Location │
├──┼────────┼───────┼──────────────────────────────────────┼──────────────────────┤
│◉ │ PFS │ 0.85 │ Error handling split 4 ways │ src/api/routes.py:42 │
│◉ │ AVS │ 0.72 │ DB import in API layer │ src/api/auth.py:18 │
│○ │ MDS │ 0.61 │ 3 near-identical validators │ src/utils/valid.py │
└──┴────────┴───────┴──────────────────────────────────────┴──────────────────────┘
Three numbers, three meanings
Drift Score (header): Overall repository coherence — higher means more structural erosion. This is an orientation metric, not a pass/fail threshold.
Finding Score (table column): Confidence that this specific finding is a real structural issue. ≥ 0.7 = strong signal, 0.4–0.7 = moderate, < 0.4 = weak.
Precision claim (site-wide): Historical accuracy of drift findings across the benchmark corpus. Currently 77% strict / 95% lenient on the v0.5 baseline. This describes methodology accuracy, not a per-repo promise.
Severity thresholds¶
Drift maps finding scores to severity levels. These thresholds determine what --fail-on blocks:
| Score | Severity | Grade | Meaning |
|---|---|---|---|
| ≥ 0.80 | CRITICAL | F | Critical structural erosion — fix before shipping |
| ≥ 0.60 | HIGH | D | Significant drift — address in current cycle |
| ≥ 0.40 | MEDIUM | C | Moderate drift — monitor, fix when touching that module |
| ≥ 0.20 | LOW | B | Minor signal — informational |
| < 0.20 | INFO | A | Negligible — healthy |
Example: drift check --fail-on high exits non-zero when any finding scores ≥ 0.60.
Understand a specific signal
Run this on whichever signal code appears in your highest-scored finding.6. How to read your first findings¶
My recommendation: start with the highest-scored findings and check if they match what already felt expensive to maintain.
- Score ≥ 0.7 → strong signal, likely a real structural issue worth investigating
- Score 0.4–0.7 → moderate signal, review when you touch that module
- Score < 0.4 → weak signal, likely noise in small repos — skip for now
Each finding links to a specific file and line. Start with the highest-scored findings and check if the pattern matches your understanding of the codebase.
Typical first-run decisions:
- You see repeated pattern variants in one module → standardize on one implementation shape before adding more features there.
- You see a boundary violation at a stable layer edge → add or tighten an architecture rule before it spreads.
- You mostly see weak findings in a small repo → keep drift in observation mode and revisit after the codebase grows.
Finding looks wrong?
Two options:
- Suppress locally: Add
# drift:context deliberate-variantabove the flagged line - Report it: 30-second false-positive report — helps improve the next release
False positives are expected on first runs. Drift improves with every report.
7. Add a safe CI gate¶
Start in report-only mode so teams can build trust before blocking merges:
When the output is stable for your team, tighten to:
8. Verify your installation¶
Drift can analyze its own codebase — useful to confirm everything works:
Next: add to your workflow¶
pre-commit (fastest path)¶
# .pre-commit-config.yaml
repos:
- repo: https://github.com/mick-gsk/drift
rev: v2.9.15
hooks:
- id: drift-report # start report-only, switch to drift-check later
CI (report-only first)¶
The recommended first step is report-only CI (no build failures):
The GitHub Action now follows the same safe default. Tighten to high only after your team has reviewed a few real runs.
See Team Rollout for the full progressive adoption path, Integrations for CI details, and Prompts to Try for copy-paste prompts you can hand to your AI assistant.
analyze vs check — when to use which¶
drift analyze |
drift check |
|
|---|---|---|
| Purpose | Full repository scan | Diff-scoped CI gate |
| Scope | All files matching include/exclude | Only changed files (--diff) |
| Typical use | Local exploration, baseline creation | Pull request CI checks |
| Output | Rich terminal, JSON, SARIF | Same formats, plus exit code gating |
| Key flags | --path, --sort-by, --format |
--fail-on, --diff, --baseline |
| Speed | Seconds to minutes (depends on repo size) | Typically < 10 seconds |
Rule of thumb: Use analyze when you want a complete picture. Use check when you want a fast CI gate on changed code.
Other commands¶
Advanced commands beyond the default first-run journey (analyze -> fix-plan -> check):
# Machine-readable JSON
drift analyze --format json
# GitHub Code Scanning (SARIF)
drift analyze --format sarif
# PR-ready Markdown summary
drift analyze --format pr-comment
# JUnit XML for CI test reporters
drift analyze --format junit
# LLM-oriented output (deprecated, prefer MCP server workflows)
drift analyze --format llm
# Track drift score over time
drift trend --last 90
# Root-cause analysis per module
drift timeline --repo . --since 90