Get started with VibeDrift

Your AI forgets between sessions.

When you use AI to write code across multiple sessions, each session starts fresh. Session 1 uses a repository pattern. Session 3 switches to raw SQL. Session 7 introduces an ORM. None are wrong individually, but together they create drift: a codebase that contradicts itself.

VibeDrift discovers the patterns your code already follows and finds the exceptions. It's a consistency checker, not a style enforcer. A codebase isn't wrong because it uses raw SQL, it's driftingbecause 8 handlers use a repository and 2 don't.

Drift also shows up as sprawl: the same logic re-implemented again and again across many files because each AI session didn't know the helper already existed. When that re-implementation is dense enough across the codebase, it's a drift signal in its own right, and deep scans now factor it into your score (see Deep scans). A single legacy parallel implementation sitting in otherwise clean code is not penalized, it's the dense, repeated reinvention that counts.

30-second setup.

VibeDrift is a Node.js CLI. You need Node 18.17+. It scans JavaScript, TypeScript, Python, Go, and Rust. No config file, no API key, no signup needed for your first scan.

Run your first scan.

The default output is an HTML report that opens in your browser. The headline is the Vibe Drift Score, 0-100 with an A-F letter grade, measuring how consistently your codebase follows its own cross-file patterns. Alongside it you get a separate, independent Hygiene Score (also 0-100) for generic quality findings like complexity, dead code, and TODOs. The two are independent, hygiene does not move the drift score. The full report is open to everyone, no account needed.

Results appear the moment the scan finishes. Signed out, the report is served on localhost; signed in, the same scan also links to your dashboard so you can track the score over time.

Tell VibeDrift what to scan.

VibeDrift checks your codebase against itself, so it's worth telling it which files are actually yours. Test fixtures, generated code, and vendored files aren't, and scoring them just adds noise. Set this up once:

init detects likely fixtures and generated code, then asks which paths to skip, your CI score floor, and your default report format. It writes two committable files:

.vibedriftignore uses gitignore syntax and is honored by both the CLI and the MCP server, so excluded paths stop counting toward your score in either (init and ignore refresh the baseline for you). Agents can set up a fresh repo in-loop too: the MCP exposes an init tool that writes the same files.

Unlock deep scans & dashboard.

Free scans run locally with no account. Sign in to unlock deep scans, the dashboard, and scan history.

Your monthly allotment (Free 1, Pro 12) and any top-up credits draw from one shared pool, so status shows both. Top-up credits never expire. Run vibedrift usage for the current billing-period scan counts and limits.

AI-powered analysis.

Deep scans add cloud AI on top of the local scan. The CLI sends function snippets only (not full files, never git history) to the VibeDrift API.

Scope a deep scan to changed files with --diff for a fast pre-PR check: vibedrift . --deep --diff compares uncommitted changes against HEAD, and vibedrift . --deep --diff main deep-scans everything that differs from a branch.

What deep scan adds:

Reimplementation scoring (0.14.6). On deep scans, the same logic re-built densely across many files lowers your Vibe Drift Score, because that's AI sprawl, not real structure. The penalty only kicks in when the reimplementation is genuinely concentrated; a single legacy or parallel implementation sitting in otherwise clean code stays informational and never costs you points. Local and free scores are unchanged by this, it applies only to the deep (AI) pass.

Deep findings aren't only a CLI thing. Your AI agent can trigger a deep check in-editor through the MCP deep-scan nudge (see MCP server); those in-loop checks draw a small fraction of a deep scan from the same shared pool.

Privacy: Only function snippets (max 60 lines each) are sent. Never full files, git history, or env vars. Processed in memory, never stored.

Local-only mode: Use --local-only to skip ALL network calls even when logged in, no scan log, no beacon, no deep analysis, no fix-prompt synthesis. Useful for:

Telemetry: Your code never leaves your machine. After each scan VibeDrift sends a small anonymous usage beacon (language, file count, lines of code, scan time, CLI version, finding count, and score, with no code, no file paths, and no identifiers), on by default for everyone whether you are signed in or not. Turn it off anytime:

You can also set VIBEDRIFT_TELEMETRY_DISABLED=1, or run --local-only for a fully offline scan with zero network calls. The CLI also checks npm about once a day for updates, controlled by the same flags.

Live peer-pattern context for your AI agent.

VibeDrift's headline feature isn't the scan report, it's the .vibedrift/ folder it writes alongside your CLAUDE.md. Commit it. Your AI coding agent reads it automatically on every new turn and knows exactly which pattern to match.

Without this, every AI session starts cold, it sees the file in front of it but not the 8 sibling files that follow your dominant pattern. So it drifts. The .vibedrift/ folder closes that gap.

One-shot, after a refactor:

Continuous, alongside your AI session:

Point it at your project while Cursor or Claude Code is working. Watch mode runs --local-only, so every save triggers a local rescan with zero network calls and the context files update before the agent's next turn.

Both --write-context and vibedrift watch need a one-time vibedrift login, the .vibedrift/ files carry the full finding surface and the Pro fix-prompt synthesis. The HTML report itself is open to everyone, no account required.

VibeDrift inside your AI agent (MCP).

The .vibedrift/ folder gives your agent context to read. The MCP server goes further: it lets Claude Code and Cursor ask VibeDrift questions while they write, "what's this repo's error-handling pattern?", "does a function like this already exist?", "would this change introduce drift?", and get an answer in well under a second. That turns drift detection into drift prevention.

The core tools are free for everyone, including signed-out users. They run entirely on your machine and never send your code, so your code never leaves your laptop. There's nothing to unlock and no plan to be on, install the server and your agent can use them right away.

Two of them, validate_change and find_similar_function, also take an opt-in deep: true that runs the full deep scan on the single function being checked, intent-mismatch detection plus AI-validated semantic duplicates, so the agent catches a misleading name or a near-clone before the code lands. This is the one metered part: deep mode sends only that one function to the API and draws a small fraction of a deep scan per check from your monthly deep-scan allotment or shared scan pool (hourly-capped, and it falls back to the local result if your budget is empty). Local tools free, deep checks metered.

1. Install the server (once per machine):

VibeDrift is a standard MCP server, there's no marketplace or extension to install. Any other client launches it with the same command. For Cursor (~/.cursor/mcp.json or project .cursor/mcp.json), and for Claude Desktop, Windsurf, Cline, VS Code, Zed and the rest, paste the same block into that client's MCP config, only the location changes, never the command:

2. Build the baseline, run one scan in the repo so the tools have your patterns to read (one-time, then cached):

3. Just code. Your agent calls these tools on its own:

What changes.Ask your agent to "add a function to cancel a subscription" and, instead of guessing, it checks your repo first:

The core tools run entirely on your machine and are free on any plan, signed in or not. If a tool returns no_baseline, run vibedrift . once to build it. The only thing that can run out is your deep-scan budget: when a deep: true check has nothing left to draw from, it quietly falls back to the local result and points you to top up.

The shapes drift takes.

Under the hood VibeDrift tracks 13 cross-file drift categories, but they roll up into a handful of patterns you'll actually recognize. These are the ones that bite. Click each to see an example.

Three layers, progressive depth.

Layer 1 and Layer 1.7 run locally on your machine (free; your code never leaves your machine, no source code or file paths are sent). Layer 2 adds cloud AI. After each scan the CLI sends a small anonymous usage beacon; turn it off with --local-only or vibedrift telemetry disable.

Most drift is caught locally for free; the deep (AI) pass adds the semantic findings, intent mismatches, and reimplementation scoring that pattern matching alone can't reach.

Understanding your score.

Score grades:

Five scoring categories:

Report sections: Overall score → Category radar → Drift findings (with code evidence) → Per-file rankings (worst to best). Start fixing from the bottom.

One category can drag the headline down. The overall score is a multiplicative blend of the five categories, so a single collapsed category (say, security with an unguarded route) pulls the whole grade down hard rather than averaging out. That's deliberate: a 95 everywhere with one 20 isn't a 76-quality codebase. Surface-specific categories with no findings (Security Posture, Intent Clarity) are shown as not-measured rather than given a free full score.

On deep scans, Redundancy also reflects concentrated reimplementation: dense cross-file reinvention of the same logic lowers the score, while a sparse or legacy parallel implementation stays informational and doesn't.

Track your progress.

When logged in, every scan is saved to vibedrift.ai/dashboard. You get:

GitHub Actions.

Set VIBEDRIFT_TOKEN as a repo secret, then add this workflow:

name: VibeDrift
on: [pull_request]

jobs:
  drift-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @vibedrift/cli . \
          --deep --json \
          --fail-on-score 70
        env:
          VIBEDRIFT_TOKEN: ${{ secrets.VIBEDRIFT_TOKEN }}

--fail-on-score 70 exits with code 1 if the score drops below the threshold, failing the PR check.

Raw CLI vs the published action. The snippet above is the universal path, npx @vibedrift/clidrops into any pipeline (GitLab, CircleCI, Jenkins, Bitbucket). If you're on GitHub and want score-delta PR comments out of the box, use the dedicated action in section 14 instead.

All commands.

Check your remaining deep-scan budget (monthly allotment + pooled top-up credits) with vibedrift status or vibedrift usage; buy a top-up from vibedrift billing or the dashboard.

What each scan includes.

Catch drift before merge.

The VibeDrift GitHub Action runs on every PR and posts a comment with the score delta + new drifts introduced. Optionally fails the check if the score drops below your threshold.

name: VibeDrift
on: [pull_request]

permissions:
  pull-requests: write

jobs:
  drift-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: skhan75/vibedrift-actions@v1
        with:
          token: ${{ secrets.VIBEDRIFT_TOKEN }}
          fail-on-score: 70
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Setup:

What you get on every PR: a comment showing the score delta (↑ or ↓ vs main), new drifts introduced, consequence lines, and a link to the full report on your dashboard.

Deep scan on release branches: add deep: ${{ github.base_ref == 'main' }} to run AI analysis only on PRs targeting main. Free scans are unlimited; deep scans draw from your monthly budget (Free 1, Pro 12). Gating deep to release branches keeps you from exhausting it on routine PRs, and if you do run out, a one-time top-up (5 scans for $10) refills the shared pool.

Monorepo: set path: packages/api to scan a subdirectory.

Any CI pipeline (not just GitHub): The GitHub Action is a convenience wrapper. The CLI works in any CI system, just run npx @vibedrift/cli . --json --fail-on-score 70 with VIBEDRIFT_TOKEN set as an environment variable.

# GitLab CI
vibedrift:
  stage: test
  script:
    - npx @vibedrift/cli . --json --fail-on-score 70
  variables:
    VIBEDRIFT_TOKEN: $VIBEDRIFT_TOKEN

# CircleCI
- run:
    name: VibeDrift
    command: npx @vibedrift/cli . --json --fail-on-score 70

# Bitbucket Pipelines
- step:
    name: VibeDrift
    script:
      - npx @vibedrift/cli . --json --fail-on-score 70

# Jenkins
stage('VibeDrift') {
  sh 'npx @vibedrift/cli . --json --fail-on-score 70'
}

The --json flag outputs the full scan result as JSON (parseable by downstream tools). --fail-on-score N exits with code 1 when the score drops below your threshold, blocking the pipeline. Add --deep for AI analysis (uses scan budget).

Offline / air-gapped: use --local-only to skip all network calls. The scan runs fully locally with no dashboard upload and no telemetry.

Simple pricing.

The local CLI scans and the MCP tools are free for everyone. You only pay for cloud deep scans, and only when you run out of your monthly allotment.

Deep-scan top-up. Out of deep scans? Grab a top-up, 5 scans for $10, one-time, buyable on both Free and Pro. Credits stack on a shared scan pool used by both CLI deep scans and in-loop MCP deep checks, and they never expire.

One shared pool.Your monthly allotment, top-up credits, and in-loop MCP deep checks all draw from and feed the same balance, so there's a single number to watch (vibedrift status), not separate buckets to reconcile.