slopbuster 0.5.1

Surgical code-sanitization engine that turns vibe-coded Python into clean, professional code.

VibeCheck

Precision cleaning for the professional engineer.

VibeCheck is a surgical code-sanitization engine. It transforms "vibe-coded" (AI-assisted or hastily written) Python into clean, professional source code by removing conversational filler, redundant documentation, and low-effort naming — without changing program behavior.

Directory support, rich reports, and a conservative approach keep it safe for real codebases. Pro tier (separate binary) adds unlimited scale and extras.

Key Features

• AI Reflective Stripper: Removes the #1 AI tell — meta comments like "Note that I've implemented...", "Hope this helps!", "As you can see...".
• Redundant Docstring Cleaner (AST-Powered): Deletes docstrings that merely echo the function or class name (e.g. def get_data(): """get data""").
• Naming Analyzer: Detects low-effort variables (data, res, tmp, result, obj...) and reports them in a dedicated table.
• Metadata-Aware Pipeline: Strategies populate rich VibeReport metadata (counts, issues list) for detailed analysis and "Boy Scout" recommendations.
• Cognitive Load Index: Multi-factor score (cyclomatic complexity via radon + slop density + nesting).
• Structural Normalizer: Collapses excessive blank lines and trims erratic whitespace.
• Boy Scout Recommendations: Actionable clean-code advice printed when issues are found.
• Pro tier: The separate vibecheck-pro binary (via Lemon Squeezy) unlocks --aggressive, full ruff format, --json-report, unlimited batch sizes, and more. The free pip package has soft limits.

Before & After

Before

# vibes
# Note that i've implemented the logic below to handle the response
def get_data(data):
    """get data"""
    # lol slop
    res = data
    return res

After (cleaned by VibeCheck)

def get_data(data):
    res = data
    return res

Report:

• Slop Indicators Removed: 3
• Structural Improvements: 1 (redundant docstring)
• Suspicious Naming: data, res flagged (see table below)

Names are reported by default; pass --fix-names to auto-rename via AST transformation.

Advanced Metrics & Reporting

VibeCheck computes a Cognitive Load Index (0-100) using:

• Cyclomatic complexity (via radon)
• Slop / vibe-keyword density
• Structural nesting depth

It produces a rich VibeReport consumed by the CLI for tables and recommendations.

Example report (with the new Naming table):

      Clarity Analysis: my_code.py        
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Metric               ┃ Value        ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Original Vibe        │ Chaotic      │
│ Clean Vibe           │ Stable       │
│ Slop Indicators Removed │ 3          │
│ Structural Improvements │ 1          │
│ Cognitive Load Index │ 42.0         │
└──────────────────────┴──────────────┘

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Suspicious Naming Detected ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Suspicious variable: res   │
│ Suspicious variable: data  │
└────────────────────────────┘

┌────────────────────────────────────────────┐
│ Boy Scout Recommendation                   │
├────────────────────────────────────────────┤
│ Suspicious variable/function names         │
│ detected. Use more descriptive names...    │
└────────────────────────────────────────────┘

See vibecheck/core/interfaces.py for the full VibeReport dataclass.

Usage

# Analyze only (no writes)
vibecheck my_code.py --report-only
# or explicitly
vibecheck clean my_code.py --report-only

# Clean the file in place (creates no backup — use git)
vibecheck my_code.py

# Auto-rename suspicious variables/functions
vibecheck src/ --fix-names

# Only clean files modified since the last commit (git-aware)
vibecheck --git

# Git-stash dirty state first then clean (safety net)
vibecheck src/ --backup

# Install a pre-commit hook to clean staged .py files
vibecheck install-hooks

The primary command is clean <path> (defaults to .). Both files and directories (recursive) are supported. Use --report-only for analysis without edits. Always commit or backup first.

Pro features (Pro binary)

The free package (pip install slopbuster) is fully functional for most use. Pro is delivered as a standalone binary via Lemon Squeezy (no key, just drop vibecheck-pro in your PATH).

# With the Pro binary in PATH (name auto-enables full features)
vibecheck-pro src/ --aggressive --json-report report.json

See vibecheck clean --help (or vibecheck-pro ...) for options. Pro removes the free tier's 10-file batch soft limit and enables aggressive patterns + ruff format + JSON export.

Example Report

      Clarity Analysis: my_code.py        
┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ Metric               ┃ Value        ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ Original Vibe        │ Chaotic      │
│ Clean Vibe           │ Professional │
│ Slop Indicators      │ 14           │
│ Cognitive Load Index │ 4.2          │
└──────────────────────┴──────────────┘

Installation

From PyPI (recommended):

pip install slopbuster
# or
uv pip install slopbuster

For development (uv recommended):

git clone ...
cd vibecheck_repo
uv sync --dev   # or uv pip install -e . -r <(uv pip compile --group dev ...)

Check version:

vibecheck --version

Free vs Pro

VibeCheck core is free and open source (MIT) on PyPI.

• Free (pip install slopbuster): Full pipeline, reports, naming fixes, git integration, hooks, etc. Soft limit: max 10 files per batch/directory operation (single files always allowed). When the limit is hit it prints an upgrade link.
• Pro (commercial binary): Unlimited files, --aggressive patterns, post-clean ruff format, --json-report, and future extras. Distributed as a standalone executable via Lemon Squeezy (no PyPI, no keys). Just place vibecheck-pro in PATH — the binary name auto-enables Pro mode.

Purchase / download the Pro binary at the Lemon Squeezy store. After purchase Lemon Squeezy emails the direct download link.

The vibecheck-pro/ build configuration lives alongside the free source (see vibecheck-pro.spec + scripts/build_pro_binary.sh).

Pro Tier

Pro features (available in the Lemon Squeezy binary):

• Unlimited batch/directory size (free has 10-file soft cap)
• --aggressive: Additional patterns (todo/hack/temp etc.)
• Post-clean ruff format (free only does ruff check --fix)
• --json-report path.json: Structured output for CI/tooling

Example (once the Pro binary is in PATH):

vibecheck-pro dirty/ --json-report report.json --aggressive

Feedback and feature requests are very welcome.

---

Donate

If VibeCheck saves you time and you want to say thanks:

• Ko-fi: https://ko-fi.com/devot

All donations fund further development of VibeCheck and sibling projects.

---

License

MIT