vibecop

AI code quality toolkit — deterministic linter for the AI coding era. 28 detectors catch the bugs AI agents introduce: god functions, N+1 queries, unsafe shell exec, unpinned LLM models, and more. Runs automatically inside Claude Code, Cursor, Codex, Aider, and 3 other AI tools via vibecop init.

Built on ast-grep for fast, tree-sitter-based AST analysis. No LLM required — every finding is deterministic and reproducible.

Try it Online

Playground — paste code and scan instantly in your browser.

Install

# npm
npm install -g vibecop

# bun (recommended)
bun add -g vibecop

Requires Node.js >= 20 or Bun >= 1.0.

Quick Start

# Scan current directory
vibecop scan .

# Scan specific directory with JSON output
vibecop scan src/ --format json

# Check what detectors are available
vibecop check

# CI mode — exit code 1 if errors found
vibecop scan . --format text

# Scan with custom config
vibecop scan . --config .vibecop.yml

Agent Integration

vibecop runs automatically inside your AI coding agent. Every time the agent edits a file, vibecop scans the change and blocks on findings — the agent reads the output and fixes the issue before proceeding.

Auto-setup (recommended)

npx vibecop init

Detects which tools you have installed and generates the right config files:

  vibecop — agent integration setup

  Detected tools:
    ✓ Claude Code (.claude/ directory found)
    ✓ Cursor (.cursor/ directory found)
    ✓ Aider (aider installed)
    ✗ Codex CLI (not found)

  Generated:
    .claude/settings.json     — PostToolUse hook (blocks on findings)
    .cursor/hooks.json        — afterFileEdit hook
    .cursor/rules/vibecop.md  — always-on lint rule
    .aider.conf.yml           — lint-cmd per language

  Done! vibecop will now run automatically in your agent workflow.

Supported tools

Manual setup (Claude Code example)

Add to .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write|MultiEdit",
      "hooks": [{
        "type": "command",
        "command": "npx vibecop scan --diff HEAD --format agent"
      }]
    }]
  }
}

How the loop works

Agent writes code
  → vibecop hook fires automatically
  → Findings? Exit 1 → agent reads output, fixes code
  → No findings? Exit 0 → agent continues

The --format agent output is token-efficient (one finding per line, ~30 tokens each):

src/api.ts:42:1 error unsafe-shell-exec: execSync() with template literal. Use execFile() with argument array instead.
src/llm.ts:18:5 warning llm-unpinned-model: Unpinned model alias "gpt-4o". Pin to a dated version like "gpt-4o-2024-08-06".

See docs/agent-integration.md for full setup instructions and troubleshooting.

Benchmarks

Vibe-coded vs established: finding density comparison

All numbers below are real — run vibecop scan on any of these repos yourself to reproduce. Finding density = findings per 1,000 lines of code.

Established projects (professionally maintained):

Vibe-coded projects (AI-generated/assisted):

Median density: established 4.4/kLOC vs vibe-coded 14.0/kLOC (3.2x higher). Vibe-coded projects consistently trigger more findings per line of code. The v0.2 detectors found 157 additional issues across vibe-coded repos that v0.1 missed: 63 unsafe shell executions, 53 unpinned LLM models, 39 missing system messages.

Note: Some established repos show higher-than-expected density for valid reasons — zod uses any deliberately for type gymnastics (634 of its 964 findings), date-fns has extensive JSDoc (218 comment-ratio findings). vibecop detects patterns, not intent. Use .vibecop.yml to tune or disable detectors for your codebase.

Example Output

src/services/user.service.ts
  45:1    error    Function 'processUserData' is too complex (232 lines, cyclomatic complexity 41, 3 params)  god-function
  89:5    warning  Database or API call inside a loop — potential N+1 query  n-plus-one-query
  145:5   warning  Database mutation result is not checked — errors will be silently ignored  unchecked-db-result

src/components/PaymentModal.tsx
  1:1     warning  Component has too many hooks (8 useState, 3 useEffect, 593 lines)  god-component
  201:9   warning  dangerouslySetInnerHTML can lead to XSS attacks if the content is not sanitized  dangerous-inner-html

src/config/auth.ts
  12:5    error    Placeholder placeholder domain found: "yourdomain.com"  placeholder-in-production
  18:5    error    Auth token stored in localStorage — vulnerable to XSS  token-in-localstorage

src/utils/api.ts
  34:12   warning  Double type assertion (as unknown as X) bypasses TypeScript's type safety  double-type-assertion
  67:1    info     TODO comment in production code (security-related)  todo-in-production

✖ 9 problems (3 errors, 5 warnings, 1 info)

Detectors (28 total)

Quality (16 detectors)

Security (7 detectors)

Correctness (4 detectors)

Testing (2 detectors)

GitHub Action

Add vibecop as a PR gate that posts inline review comments on changed lines:

# .github/workflows/vibecop.yml
name: vibecop
on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: bhvbhushan/vibecop@main
        with:
          on-failure: comment-only    # or: request-changes, label, auto-close
          severity-threshold: warning
          max-findings: 50

Action Inputs

Action Outputs

Configuration

Create .vibecop.yml in your project root:

rules:
  god-function:
    severity: warning
  debug-console-in-prod:
    severity: "off"        # disable a detector
  excessive-any:
    severity: warning

ignore:
  - "**/dist/**"
  - "**/vendor/**"
  - "**/generated/**"

pr-gate:
  on-failure: request-changes
  severity-threshold: warning
  max-findings: 50
  label: "vibecop:needs-review"

CLI Options

Languages

Architecture

vibecop CLI (Commander)
+-- Scan Engine           -- discovers files, loads AST, runs detectors, dedup by priority
+-- Init Wizard           -- auto-detects AI tools, generates hook/rule configs
+-- Config Loader (Zod)   -- validates .vibecop.yml, merges defaults, per-rule config
+-- Detectors (28)        -- AST pattern matching via ast-grep (@ast-grep/napi)
+-- Formatters (6)        -- text, json, html, sarif, github, agent output
+-- Project Analyzer      -- parses package.json, requirements.txt, lockfiles
+-- GitHub Action          -- diff parser, finding filter, PR review poster

Versioning

vibecop follows Semantic Versioning:

• 0.x.y ... pre-1.0, the API may change between minor versions
• PATCH (0.x.Y) ... bug fixes, new detectors, doc updates
• MINOR (0.X.0) ... new detector categories, output formats, config options
• MAJOR (X.0.0) ... breaking CLI changes, removed detectors, config format changes

Roadmap

• Phase 1: Core scanner with 7 detectors, 5 output formats, .vibecop.yml config
• Phase 2: PR Gate GitHub Action, 15 new detectors (7 → 22), real-world validation
• Phase 2.5: Agent integration (7 tools), 6 LLM/agent detectors (22 → 28), vibecop init, --format agent
• Phase 3: MCP server, VS Code extension, cross-file analysis
• Phase 4: LLM-powered deep review mode (separation of concerns, semantic duplication)

Contributing

See CONTRIBUTING.md for development setup, code standards, and how to add new detectors.

Security

See SECURITY.md for reporting vulnerabilities.

Code of Conduct

See CODE_OF_CONDUCT.md.

License

MIT