CodeVibes

Brutally honest repository analysis for local projects and GitHub repos.

CodeVibes scans a codebase, calculates engineering + "repo vibe" signals, and outputs a report in text, markdown, or JSON. It can also submit JSON to a webhook and enforce CI thresholds.

1.1.0 Scope

• Local path scan and GitHub URL scan (shallow clone to temp dir)
• Diff analysis against:
  • git refs (--base/--head)
  • saved baseline JSON (--baseline)
• Security findings and vibe findings in one report
• Core scores:
  • Risk Score
  • Naming Chaos Index
  • Structure Score
  • Complexity Score
  • Vibe Score
• One-line Overall Verdict
• Output formats: text, markdown, json
• Optional webhook submission
• Optional CI fail policies
• Regression-aware diff fail policies:
  • --fail-on-risk-regression
  • --fail-on-vibe-drop
  • --fail-on-new-findings
  • --fail-on-new-high
• Config via .codevibes.json
• .gitignore + glob include/exclude support
• Next.js frontend dashboard (Scan + Diff) with legacy fallback

Install

Python 3.10+ is required.

pip install .

After install:

codevibes scan .

CLI Usage

codevibes scan <path-or-github-url> [options]

codevibes diff [path] [options]

Diff Mode

Compare only changed files instead of scanning the entire repository.

codevibes diff . --base main --head HEAD

or compare against a saved JSON baseline:

codevibes diff . --baseline reports/baseline.json

Diff output includes:

• newly introduced findings
• score regressions caused by this change
• degradation source files
• prioritized fix suggestions with estimated risk reduction

Regression-focused CI gates:

• --fail-on-risk-regression N
• --fail-on-vibe-drop N
• --fail-on-new-findings N
• --fail-on-new-high N

Web UI

Launch local dashboard (Next.js frontend, default):

codevibes ui

Default address is http://127.0.0.1:8765. If ui/node_modules is missing, codevibes ui runs npm install automatically. You can still force the old Python UI with --legacy during migration.

UI options:

• --host: bind host (default: 127.0.0.1)
• --port: bind port (default: 8765)
• --no-browser: do not auto-open browser
• --frontend {next,legacy}: choose frontend runtime (default: next)
• --legacy: force legacy Python inline UI
• --skip-install: do not auto-run npm install
• --clone-timeout SECONDS: git clone timeout for GitHub scans

Frontend workspace:

• ui/app/page.tsx: main Scan + Diff dashboard
• ui/app/api/scan/route.ts: scan API bridge to Python CLI
• ui/app/api/diff/route.ts: diff API bridge to Python CLI
• ui/lib/types.ts: shared frontend response types

Frontend local development:

cd ui
npm install
npm run dev

Then open http://localhost:3000.

Arguments

• path: local project path, or https://github.com/<owner>/<repo>

Options

• --format {text,markdown,json}: output format (default: text)
• --top-files N: number of top long files to show (default: 5)
• --max-findings N: max findings shown in detail sections (default from config, fallback 50)
• --output PATH: save report to file instead of stdout
• --roast: use more sarcastic verdict style
• --fail-on-risk N: exit non-zero when risk_score >= N (0..100)
• --fail-on-findings N: exit non-zero when total_findings >= N
• --submit-webhook URL: POST JSON report to webhook
• --submit-timeout SECONDS: webhook timeout (default: 10)
• --clone-timeout SECONDS: git clone timeout for GitHub URL scans (default: 30)

Diff Options

• --base REF: base git ref (default: main)
• --head REF: head git ref (default: HEAD)
• --baseline PATH: baseline JSON generated by scan --format json
• --format {text,markdown,json}: output format (default: text)
• --max-findings N: max new/resolved findings shown (default: 50)
• --output PATH: save diff report to file
• --fail-on-risk-regression N: fail when risk regression is greater than N
• --fail-on-vibe-drop N: fail when vibe drop is greater than N
• --fail-on-new-findings N: fail when new findings are greater than N
• --fail-on-new-high N: fail when new high+critical findings are greater than N

Examples

codevibes scan .
codevibes scan . --format markdown
codevibes scan . --format json --output reports/latest.json
codevibes scan . --top-files 10 --max-findings 80
codevibes scan . --roast
codevibes scan . --fail-on-risk 70 --fail-on-findings 25
codevibes scan . --submit-webhook https://example.com/hook
codevibes scan https://github.com/user/repo --clone-timeout 45
codevibes ui --port 9000 --no-browser
codevibes ui --legacy
codevibes diff . --base main --head HEAD --format markdown
codevibes diff . --baseline reports/baseline.json --fail-on-new-high 0
codevibes-ui --port 8765

Exit Codes

• 0: success
• 1: input/scan/runtime error
• 2: policy failure (--fail-on-risk or --fail-on-findings)
• 3: webhook submission failure

Config File: .codevibes.json

Put this file in project root to override defaults.

{
  "included_extensions": [".py", ".ts", ".md"],
  "excluded_extensions": [".min.js"],
  "excluded_dirs": [".git", "node_modules", "dist"],
  "include_globs": ["src/**", "*.py"],
  "exclude_globs": ["coverage/**", "generated/**", "*.snap"],
  "respect_gitignore": true,
  "generic_folder_names": ["utils", "helpers", "common", "misc", "shared", "temp"],
  "suspicious_name_keywords": ["temp", "final", "backup", "copy", "new", "old", "test2"],
  "line_thresholds": {
    "medium": 300,
    "high": 500,
    "critical": 800
  },
  "max_findings_default": 50
}

Notes:

• line_thresholds and oversized_file_line_thresholds are both accepted.
• Extensions can be with or without leading dot.
• Legacy config filename from early builds is still supported.

Webhook Payload

When --submit-webhook is set, JSON payload includes:

• scan_report
• scorecard
• top_suspicious_files
• security_findings
• vibe_findings
• verdict
• submission_metadata:
  • project_path
  • submitted_at (UTC ISO-8601)
  • tool_version

Project Structure

codevibes/
├─ main.py
├─ README.md
├─ pyproject.toml
└─ core package/
   ├─ __init__.py
   ├─ cli.py
   ├─ config.py
   ├─ models.py
   ├─ rules.py
   ├─ scanner.py
   ├─ scoring.py
   └─ formatter.py

Development

Run tests:

python -m unittest discover -s tests -p "test_*.py" -v

Local run without installation:

python main.py scan .

Backward-compatible shortcut is still supported:

python main.py .

Legacy CLI alias is still supported for compatibility.