Quick Start

npx vibeclean

One command. Zero config.

PR-focused mode:

npx vibeclean --changed --base main

What It Detects

• 🔀 Pattern inconsistencies (multiple HTTP clients, mixed async styles, mixed imports)
• 📝 Naming chaos (camelCase + snake_case + mixed file naming)
• 🗑️ AI leftovers (TODO/FIXME, console logs, placeholders, localhost URLs)
• 🔐 Security exposure (hardcoded keys/tokens, private keys, credential URLs)
• 📦 Dependency bloat (unused packages, duplicate functionality, deprecated libs)
• 💀 Dead code (orphan files, unused exports, stubs)
• ⚠️ Error handling gaps (empty catches, unhandled async, mixed error patterns)
• 🧠 TypeScript quality drift (explicit any, ts-ignore overuse, assertion style mix)
• 🧱 Framework anti-patterns (React/Next.js/Express hotspots)

Example Output

  🧹 vibeclean v1.0.0 — Cleaning up the vibe

  Scanning project... ✓ Found 124 source files in 0.8s

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ⚠️  NAMING INCONSISTENCY                         Score: 6/10
     ├─ camelCase: 72%, snake_case: 28%
     ├─ Mixed directories: 4
     └─ Component filename mismatches: 3

  ⚠️  PATTERN INCONSISTENCY                        Score: 8/10
     ├─ HTTP clients: fetch (12), axios (5), got (1)
     ├─ Mixed async: async/await (78%), .then() (22%)
     └─ Module style: import files 25, require files 6

  🚨 AI LEFTOVERS                                  Score: 7/10
     ├─ console.* statements: 23
     ├─ TODO/FIXME markers: 12 (8 AI-like)
     └─ Placeholders/localhost: 9

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  📊 VIBE CLEANLINESS SCORE: 38/100
     Your codebase has significant vibe coding debt.

  🧹 Found 67 issues across 6 categories
  📋 Run vibeclean --rules to generate AI rules file

Vibe Cleanliness Score

Each category gets a score from 0-10 (higher = more inconsistency). vibeclean converts this into an overall score out of 100 (higher = cleaner).

• 80-100: consistent and clean
• 60-79: manageable debt
• 40-59: visible inconsistency debt
• <40: significant vibe debt

Generate Rules for AI Assistants

vibeclean --rules
vibeclean --rules --cursor --claude

Generated files:

• .vibeclean-rules.md
• .cursorrules (optional)
• CLAUDE.md (optional)

These encode your dominant project conventions so future AI-assisted code stays consistent.

CLI Usage

Usage: vibeclean [options] [directory]

Arguments:
  directory                Project directory to scan (default: current directory)

Options:
  -f, --fix               Apply safe autofixes before scoring (TODO/commented code/noisy console)
  --json                  Output results as JSON
  --report <format>       Output format: text, json, markdown (default: text)
  --report-file <path>    Write report output to file
  --profile <name>        Preset profile: app, library, cli (default: app)
  --changed               Scan only changed files in the current git working tree
  --base <ref>            Git base ref to diff against when using --changed (default: HEAD)
  --baseline              Compare against baseline file and detect regressions
  --baseline-file <path>  Baseline file path for compare/write (default: .vibeclean-baseline.json)
  --write-baseline        Write current report to baseline file
  --watch                 Watch files and re-run audit on changes
  --watch-interval <ms>   Polling interval fallback for --watch (default: 1200)
  --ci-init               Generate a GitHub Actions workflow for vibeclean checks
  --ci-force              Overwrite existing workflow when used with --ci-init
  --rules                 Generate .vibeclean-rules.md file
  --cursor                Also generate .cursorrules file
  --claude                Also generate CLAUDE.md file
  --min-severity <level>  Minimum severity: low, medium, high (default: low)
  --fail-on <level>       Fail if findings hit this severity: low, medium, high
  --max-issues <n>        Fail if total issues exceed this number
  --min-score <n>         Fail if overall score is below this threshold (0-100)
  --ignore <patterns>     Additional ignore patterns (comma-separated)
  --max-files <n>         Maximum files to scan (default: 500)
  -q, --quiet             Summary output only
  -v, --version           Show version
  -h, --help              Show help

CI / PR Quality Gates

# Fail CI on high-severity findings in changed files only
vibeclean --changed --base main --fail-on high

# Fail if quality drifts too far
vibeclean --min-score 75 --max-issues 20

When a gate fails, vibeclean exits with status code 1.

Profiles

# Default
vibeclean --profile app

# Libraries: ignores common example/benchmark folders
vibeclean --profile library

# CLI projects: reduces test/bin leftovers noise
vibeclean --profile cli

Profiles apply sensible defaults, but you can still override with .vibecleanrc and --ignore.

Baseline Compare

# Create baseline snapshot
vibeclean --write-baseline --baseline-file .vibeclean-baseline.json

# Compare current branch against baseline (fails on regressions by default)
vibeclean --baseline --baseline-file .vibeclean-baseline.json

Baseline compare tracks:

• overall score drift
• issue count drift
• high-severity finding drift
• category-level score regressions

Markdown PR Report

# Print markdown to stdout
vibeclean --report markdown

# Write markdown report to file for PR comments/artifacts
vibeclean --report markdown --report-file vibeclean-report.md

Watch Mode

vibeclean --watch --profile cli

This re-runs the audit when files change using lightweight polling.

CI Workflow Bootstrap

vibeclean --ci-init --profile cli --baseline-file .vibeclean-baseline.json --min-score 70 --max-issues 35 --fail-on high

Generates .github/workflows/vibeclean.yml with a PR-ready baseline + gates command.

Autofix Mode

vibeclean --fix

Safe autofix currently removes:

• TODO/FIXME/HACK/XXX comment lines
• obvious commented-out code blocks
• standalone console.log/debug/trace lines

After fixes are applied, vibeclean re-scores the project and reports what changed.

Configuration

Create .vibecleanrc or .vibecleanrc.json in project root:

{
  "maxFiles": 500,
  "changedOnly": false,
  "changedBase": "main",
  "profile": "app",
  "baseline": false,
  "baselineFile": ".vibeclean-baseline.json",
  "failOnRegression": true,
  "reportFormat": "text",
  "ignore": ["scripts/", "*.test.js", "*.spec.js"],
  "severity": "medium",
  "failOn": "high",
  "maxIssues": 30,
  "minScore": 70,
  "rules": {
    "naming": true,
    "patterns": true,
    "leftovers": true,
    "security": true,
    "frameworks": true,
    "dependencies": true,
    "deadcode": true,
    "errorhandling": true,
    "tsquality": true
  },
  "allowedPatterns": {
    "httpClient": "fetch",
    "asyncStyle": "async-await",
    "stateManagement": "zustand"
  }
}

Why vibeclean?

ESLint checks syntax and style. SonarQube checks quality and vulnerabilities.

vibeclean checks the specific mess that AI coding creates: pattern inconsistency across sessions.

Contributing

See CONTRIBUTING.md.

Development

npm install
npm test
node bin/vibeclean.js .

License

MIT — see LICENSE.