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.

30-second setup.

VibeDrift is a Node.js CLI. You need Node 18.17+. 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. As of v0.6.0 you get two independent scalars: a Vibe Drift Score (max 80) measuring cross-file pattern consistency, and a Hygiene Score (max 100) for generic quality findings. The drift score is the headline — hygiene does not affect it.

Unlock deep scans & dashboard.

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

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.

What deep scan adds:

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: When logged in, VibeDrift sends a lightweight anonymous beacon per scan (language, file count, scan time — no code, no file paths). Opt out anytime:

Not-logged-in scans make zero network calls by default — no opt-out needed.

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. Every save triggers a local rescan (zero network) 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, same gate as the HTML report.

Six types of drift.

VibeDrift finds cross-file contradictions that no linter catches. Click each type to see an example.

Four layers, progressive depth.

Layers 1-3 run locally on your machine (free, no data sent). Layer 4 adds cloud AI.

A free scan catches ~70% of issues with local analysis. Deep scan adds AI for the remaining 30%.

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.

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.

All commands.

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 use your monthly budget.

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.