driftguard

Your AI coding agent will build anything you ask. driftguard asks whether you should.

Audits your Claude Code · Codex · Antigravity · Cursor history, interviews you, hosts an interactive report on localhost, and writes drift guards into your agent's rules, so the next session catches you before a bug fix turns into a new app.

Live demo → · Website · Install · How it works · Token crisis mode

Why

Vibe coding makes starting things free. The cost shows up later: seven half-built side projects, a usage limit hit every week, and prompts that slid from "fix these 3 bugs" to "uhhh make it 3D or whatever".

Typical patterns driftguard surfaces from your own history:

• a burst month where most sessions went into projects you never use
• focus breaking right after the first answer: the second prompt is a new topic, a long absence, or frustration
• vague delegation ("do whatever you want") right before the sessions you rage at

Analytics tools show you numbers. driftguard turns them into rules your agent follows every session.

What you get

_{3D "brain terrain": prompts per hour × weekday; red = where you disconnect. Drag to rotate in the live demo.}

Install

pipx install driftguard-cli        # or: uv tool install driftguard-cli   ·   pip install --user driftguard-cli

One-liners that also install the agent integrations they find:

curl -fsSL https://raw.githubusercontent.com/stelies/driftguard/main/scripts/install.sh | sh       # macOS / Linux / WSL

irm https://raw.githubusercontent.com/stelies/driftguard/main/scripts/install.ps1 | iex           # Windows

Windows is native: no WSL, no Node, no admin rights. PowerShell or cmd, with Python 3.9+ (winget install Python.Python.3.13). It reads Claude Code from %USERPROFILE%\.claude, and the driftguard pulse hook works there unchanged.

/plugin marketplace add stelies/driftguard
/plugin install driftguard@driftguard

{ "hooks": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "driftguard pulse" } ] } ] } }

Use

driftguard scan                 # read every agent's history (incremental, ~0.5 s warm)
driftguard report --serve       # metrics-only report on localhost, no LLM needed
/driftguard                     # in your agent: scoring + interview + verdicts + guards

How it works

flowchart LR
  subgraph local["Your machine (nothing leaves it)"]
    H[("~/.claude · ~/.codex<br/>~/.gemini · Cursor DB")] -->|scan, 0 tokens| S[scan.json + metrics]
    S -->|digest, 0 tokens| D[prompt-only chunks]
    D -->|your agent scores| F[findings.json]
    S --> M{mode}
    M -->|new user| X[scaled-up diagnostics]
    M -->|heavy usage| Y[frugal mode]
    F --> I[[interview polls]]
    I -->|answers override| F
    F --> R[report.html on localhost]
    F --> G[guard blocks → CLAUDE.md / AGENTS.md / GEMINI.md / .cursor/rules]
    G -.->|every session| A((your agent stops<br/>and asks before drifting))
  end

Two layers. A deterministic, dependency-free Python CLI does all reading and math. Your agent does only the judgment (scoring prompt digests, interviewing you, wording the guards). Raw transcripts never enter the model's context.

It adapts to you:

• New user (fewer than ~15 sessions, under 3 weeks, or no rules/skills/hooks yet): every metric is explained, Setup health comes first, starter rewrites use your own prompts, and you get fewer verdicts.
• Heavy usage (limit talk in prompts, spend concentrated in a few sessions, recent 5h blocks above your p90): Haiku/Sonnet subagents, at most 2 at once, smaller digests, an optional scoring pass, and token-saver rules added to your guard.

The disconnect heuristics

They're heuristics, and the report says so. The interview exists because only you know whether a project was a waste.

Token crisis mode

If you're about to hit your limit:

driftguard budget          # where the tokens went, per 5-hour block
driftguard handoff         # ≤40-line HANDOFF.md: goal, files touched, open todos, last asks, next step

Then start a fresh session: "read HANDOFF.md and continue". Your guard also gains rules such as cheap subagents ≤2, digests instead of transcripts, never re-reading files, and compacting at boundaries.

Privacy

• Everything runs locally. The CLI makes no network calls.
• The scoring pass runs inside your own agent session, under your plan, like any other prompt.
• Transcript text is treated as data: the skill tells your agent never to follow instructions found inside old messages.
• guard is a dry run until you pass --apply, and every changed file gets a .bak.
• The live demo uses a synthetic dataset.

driftguard vs. the rest (use them together)

If you only want token numbers, use ccusage. If you want the agent to stop you from starting project #8, use driftguard.

FAQ

Contributing

git clone https://github.com/stelies/driftguard && cd driftguard
python -m pip install -e ".[dev]" && python -m pytest -q
cd web && npm ci && npm run build      # rebuilds driftguard/report/template.html
python scripts/make_demo_data.py --out /tmp/demo.html

Adapter fixes with a fixture are especially welcome. Report UI: SvelteKit + Tailwind with components from llama.cpp's web UI (MIT).

License

MIT © stelies