# VibeDrift

> VibeDrift is an open-source CLI and MCP server that detects and prevents AI coding agent drift by scanning your codebase for architectural inconsistencies, duplicates, and convention violations across sessions.

VibeDrift is an MIT-licensed CLI tool and MCP server built to solve a specific problem with AI coding agents: as a project grows across multiple sessions, each new session starts cold and gradually introduces contradictions — different data access patterns, inconsistent error handling, duplicate logic under different names. VibeDrift scans your codebase against itself, learns the dominant patterns by majority vote, and flags every deviation with file-level evidence. It is free to use locally, open source on GitHub, and integrates with Claude Code, Cursor, Windsurf, GitHub Copilot, and any MCP-compatible client.

## What It Is

VibeDrift is a code consistency checker for AI-generated codebases. Unlike linters that validate one file at a time against syntax rules, VibeDrift compares files against each other to find cross-file architectural contradictions — for example, eight handlers using a repository pattern while two reach for raw SQL. It produces a **Vibe Drift Score** (0–100, graded A–F) and a separate **Hygiene Score**, both grounded in the codebase's own conventions rather than a generic rulebook. The tool supports JavaScript, TypeScript, Python, Go, and Rust, and runs entirely on your machine with no signup required for local scans.

## Three-Layer Analysis Architecture

VibeDrift processes codebases in progressive depth:

- **Layer 1 — Static + Cross-File Analysis:** 12 static analyzers covering naming, imports, error handling, complexity, and security, plus 8 cross-file drift detectors that identify the dominant pattern and flag deviations. Runs locally, free.
- **Layer 1.7 — Code DNA:** Structural fingerprinting, hash-based duplicate detection, operation sequence analysis, and taint tracking. Also local and free.
- **Layer 2 — Deep Scan (AI):** ML semantic embeddings for duplicates static analysis can't see, intent mismatch detection (when a function's name doesn't match its behavior), AI validation of borderline findings, concentrated-reimplementation scoring, and an AI-generated coherence report. Requires a login and draws from a monthly deep-scan allotment.

## MCP Server: From Detection to Prevention

The MCP server is VibeDrift's headline prevention feature. It lets AI coding agents query the codebase's own conventions mid-task — before writing a line — and get an evidence-backed answer in under a second. Five tools are exposed:

- `get_dominant_pattern` — returns the repo's majority convention for a dimension with copy examples
- `find_similar_function` — checks whether a near-duplicate already exists
- `check_file_drift` — validates whether a file matches the repo's patterns
- `validate_change` — checks whether a proposed change would introduce drift
- `get_intent_hints` — reads declared conventions from `CLAUDE.md`, `AGENTS.md`, or `.cursorrules`

All five core tools run entirely on the local machine, send no code, and require no login. The `validate_change` and `find_similar_function` tools support an optional `deep: true` mode that sends only the single function being checked to the API and draws a small fraction of a deep scan from the shared pool.

## Agent Memory and Watch Mode

Every scan writes a `.vibedrift/` folder alongside `CLAUDE.md` containing `context.md` (dominant patterns and open drifts), `fix-plan.md` (top 10 drifts with copy-paste fix prompts), `fix-prompts.md` (per-finding prompts), and `patterns.json` (machine-readable pattern data). Committing this folder means every new AI session starts with up-to-date peer context rather than a cold start. Watch mode (`vibedrift watch`) rescans on every file save and refreshes these files continuously with zero network calls, keeping the agent's context current throughout a session.

## CI/CD Integration

VibeDrift ships a GitHub Action (`skhan75/vibedrift-actions@v1`) that runs on pull requests, posts a score-delta comment showing new drifts introduced, and can fail the check if the score drops below a configurable threshold via `--fail-on-score`. The raw CLI also works in GitLab CI, CircleCI, Bitbucket Pipelines, and Jenkins using `npx @vibedrift/cli . --json --fail-on-score 70` with a `VIBEDRIFT_TOKEN` environment variable. A `--local-only` flag skips all network calls for air-gapped or restricted environments.

## Update: v0.14.9

The latest release is **v0.14.9**, published on 2026-07-07, with the repository last pushed the same day. Version 0.14.6 introduced reimplementation scoring on deep scans — concentrated cross-file reinvention of the same logic now lowers the Vibe Drift Score, while sparse or legacy parallel implementations remain informational. The project was announced as open source recently (MIT license, 46 GitHub stars at time of writing) and the changelog notes that new detectors and calibration improvements land most weeks.

## Features
- Cross-file drift detection comparing files against each other
- Vibe Drift Score (0-100, A-F grade) based on codebase's own conventions
- Hygiene Score for generic quality findings (complexity, dead code, TODOs)
- MCP server with 5 tools for in-loop drift prevention
- Agent memory via .vibedrift/ folder (context.md, fix-plan.md, patterns.json)
- Watch mode: rescan on every file save, zero network calls
- Deep scan: AI-powered semantic duplicate detection and intent mismatch detection
- Code DNA structural fingerprinting and hash-based duplicate detection
- 13 cross-file drift categories including architectural contradictions, security gaps, naming inconsistency
- CI/CD integration with GitHub Action and --fail-on-score flag
- Scan-over-scan delta showing what changed since last scan
- Local-only mode for air-gapped environments
- Support for JavaScript, TypeScript, Python, Go, and Rust
- HTML, terminal, JSON, CSV, and DOCX report formats
- Pre-push git hook for drift-score gating
- Dashboard with score timeline, scan history, and project grouping

## Integrations
Claude Code, Cursor, GitHub Copilot, Windsurf, Antigravity, OpenAI Codex, Kiro, Claude Desktop, VS Code, Zed, GitHub Actions, GitLab CI, CircleCI, Bitbucket Pipelines, Jenkins, npm

## Platforms
WEB, API, VSC_EXTENSION, DEVELOPER_SDK, CLI

## Pricing
Open Source, Free tier available

## Version
v0.14.9

## Links
- Website: https://vibedrift.ai
- Documentation: https://www.vibedrift.ai/guide
- Repository: https://github.com/VibeDrift/VibeDrift
- EveryDev.ai: https://www.everydev.ai/tools/vibedrift