vibegate 0.6.2

Deterministic production readiness gate for Python projects.

VibeGate

VibeGate makes code quality checks friendly and actionable.

It's a powerhouse quality engine under the hood—running all your Python checks in one command—but surfaces results in plain English with clear next steps.

5 Minute Quickstart

1. Install:

pip install "vibegate[tools]"

2. Run checks:

vibegate run .

3. View results:

Open .vibegate/plain_report.md or use the web viewer:

vibegate view .  # Opens at http://127.0.0.1:8787

That's it! VibeGate works without config, checks your tools, runs quality checks, and shows you what to fix.

Exit codes: 0 = PASS, 1 = FAIL, 2 = CONFIG ERROR

📖 New to VibeGate? Read the Getting Started Guide for a complete walkthrough including profiles, CI setup, and troubleshooting.

What VibeGate Creates

When you run vibegate run ., you get these files:

File	What It Is	Who It's For
.vibegate/plain_report.md	Friendly report in plain English	Everyone
.vibegate/artifacts/vibegate_report.md	Technical details and metrics	Developers & CI
.vibegate/artifacts/fixpack.json	Machine-readable action plan	Tools & automation
.vibegate/agent_prompt.md	Instructions for AI coding assistants	Claude Code, GitHub Copilot, Cursor
.vibegate/agent_prompt.json	Machine-readable AI instructions	AI agents
.vibegate/evidence/vibegate.jsonl	Complete audit trail (proof log)	Compliance & debugging

What's the difference between reports?

• Plain Report (.vibegate/plain_report.md): Explains what's wrong in simple terms, why it matters, and what to do about it
• Technical Report (.vibegate/artifacts/vibegate_report.md): Shows you exact file paths, line numbers, error codes, and technical details
• Fix Pack (.vibegate/artifacts/fixpack.json): Lists every issue as a task with step-by-step fix instructions

Friendly vs Deep Detail

You can control how much information VibeGate shows you:

# Simple mode (default) - just the highlights
vibegate run .

# Deep mode - includes all technical details
vibegate run . --detail deep

In simple mode, the plain report shows you the first few examples of each type of problem.

In deep mode, you get everything: full finding lists, severity breakdowns, fingerprints, and proof logs.

Important: The detail flag only changes what's shown in the plain report. The gate decision (PASS or FAIL) is always deterministic and never changes based on detail level.

Optional: Local Model Helpers

VibeGate can use a local AI model to make code quality issues easier to understand. The helper runs entirely on your machine—no data leaves your computer.

What the helper does

• Plain English explanations of technical findings
• Better fix prompts for AI coding assistants
• Context-aware suggestions based on your actual code patterns

Two ways to run helpers locally

Option 1: Ollama (Easy path)

Install Ollama:

# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Download from https://ollama.com/download

Run the setup wizard:

vibegate init .

The wizard will:

1. Detect Ollama
2. Let you choose a model
3. Download it for you
4. Add the config to vibegate.yaml

Example config (added automatically by the wizard):

llm:
  enabled: true
  provider: ollama
  cache_dir: .vibegate/llm_cache
  ollama:
    base_url: http://localhost:11434
    model: qwen2.5-coder:7b
    temperature: 0.3
  features:
    explain_findings: true
    generate_prompts: true

Option 2: OpenAI-Compatible Server (Advanced)

If you're running a local OpenAI-compatible server like vLLM, LM Studio, or llama.cpp server:

llm:
  enabled: true
  provider: openai_compatible
  cache_dir: .vibegate/llm_cache
  openai_compatible:
    base_url: http://localhost:8000/v1  # Your local server
    model: Qwen/Qwen2.5-Coder-7B-Instruct
    temperature: 0.3
    timeout_sec: 60
    # extra_headers: {}  # Optional: for auth if your server requires it
  features:
    explain_findings: true
    generate_prompts: true

Note: Most local servers don't require authentication. If your server does, use extra_headers:

    extra_headers:
      Authorization: "Bearer <your-token>"

Model picker

Here's a quick guide to choosing a model:

Model	Speed	Quality	Memory	Notes
Qwen2.5-Coder 7B	⚡⚡⚡	⭐⭐⭐	4GB	Default choice. Fast, good quality
Qwen2.5-Coder 14B	⚡⚡	⭐⭐⭐⭐	8GB	Better explanations, slower
DeepSeek-Coder-V2 16B	⚡	⭐⭐⭐⭐⭐	10GB	Best quality, needs powerful machine
CodeLlama 7B	⚡⚡⚡	⭐⭐	4GB	Older, still works fine

License note: These models can be run locally because the weights are available. Licenses vary (some are OSI licenses like Apache 2.0, others are custom model licenses). Always check the model license before production use:

• Qwen2.5-Coder 7B/14B: Apache 2.0
• DeepSeek-Coder-V2: Model License applies to weights; code is MIT
• Code Llama: Llama license terms

To use these models with Ollama:

# For Qwen (recommended)
ollama pull qwen2.5-coder:7b
# or
ollama pull qwen2.5-coder:14b

# For DeepSeek (requires more memory)
ollama pull deepseek-coder-v2:16b

# For CodeLlama
ollama pull codellama:7b

Philosophy: Deterministic Core + Optional Helper

The gate decision (PASS or FAIL) is always deterministic. It never involves AI models.

The optional helper model is used ONLY to:

1. Translate technical findings into friendly English
2. Generate better prompts for AI coding assistants
3. Suggest context-aware fixes

The helper cannot and does not:

• Change whether the gate passes or fails
• Suppress findings
• Modify your code
• Send data to external services

Contributing and Roadmap

Want to contribute or see what's planned?

• Getting started: docs/GETTING_STARTED.md - Complete quickstart guide
• Product vision: docs/PRODUCT_VISION.md
• Technical architecture: docs/ARCHITECTURE.md
• Local model setup: docs/LOCAL_MODELS.md
• Roadmap: docs/OPEN_CORE_ROADMAP.md
• Contributing guide: CONTRIBUTING.md
• Release process: docs/RELEASING.md

What Checks Run

VibeGate orchestrates comprehensive quality checks:

Always enabled (if tools available)

• Code formatting (ruff format)
• Linting (ruff check)
• Type checking (pyright)
• Tests (pytest)
• Dependency hygiene (lockfile validation)
• Configuration safety (debug mode detection, CORS wildcards, secrets in code)
• Error handling (empty except blocks, missing logging)
• Defensive programming (None checks, array bounds, zero division)
• Code complexity (function length, nesting depth)
• Dead code detection (unreachable code, commented code)

Optional (when tools installed)

• Security scanning (bandit)
• Secret detection (gitleaks)
• Vulnerability scanning (osv-scanner, offline mode)
• Advanced dead code (vulture)

Framework-specific (when configured)

• Runtime smoke tests (FastAPI, Django, Flask - optional)

Installation Options

For running on other projects (recommended)

pipx install "vibegate[tools]"

This keeps VibeGate isolated and available globally.

In a project virtualenv

pip install "vibegate[tools]"

Minimal (no quality tools bundled)

pip install vibegate

You'll need to install ruff, pyright, pytest, etc. separately.

For VibeGate contributors

git clone https://github.com/maxadamsky/VibeGate.git
cd VibeGate
pip install -e ".[dev]"

Common Workflows

One-command workflow (humans)

vibegate run .

Does everything: verify tools, run checks, show friendly summary.

Evolution workflow (maintainers)

vibegate evolve .

Full cycle: check → triage (optional) → tune → propose

This helps you improve check quality over time by:

1. Running checks
2. Letting you label findings (false positive / true positive / acceptable risk)
3. Generating tuning insights from labeled findings
4. Creating actionable proposals for rule refinement

Step-by-step workflow (CI or manual control)

vibegate init .      # Create config (optional)
vibegate doctor .    # Verify tools
vibegate run .       # Run checks (recommended)
vibegate triage .    # Label findings (interactive)
vibegate tune .      # Generate tuning insights
vibegate propose .   # Create proposal pack

From source (without installing console script)

python -m vibegate run .

Cleaning Up

VibeGate provides a safe cleanup command to remove cache directories and build artifacts:

# Preview what would be deleted (recommended first step)
vibegate clean . --dry-run

# Clean standard caches (safe - preserves config files)
vibegate clean .

# Include UI runs and LLM cache
vibegate clean . --all

# Also delete virtual environments (.venv, .venv-*)
vibegate clean . --venv

# Combine flags
vibegate clean . --all --venv

What gets cleaned by default:

• Python caches: .pytest_cache, .ruff_cache, .mypy_cache, __pycache__ (recursive)
• Build artifacts: dist/, build/, *.egg-info
• Coverage reports: htmlcov/, .coverage
• Tool caches: .tox/, .nox/

What's always preserved:

• vibegate.yaml
• .vibegate/suppressions.yaml
• .vibegate/labels.yaml
• .vibegate/llm_cache (unless --all specified)
• .vibegate/ui/runs (unless --all specified)
• Virtual environments (unless --venv specified)

Tip: Always run with --dry-run first to preview what will be deleted.

Framework Integration

FastAPI

# vibegate.yaml
project:
  app_module: "app.main:app"

checks:
  runtime_smoke:
    enabled: true
    command: "uvicorn app.main:app --host 127.0.0.1 --port 8000"
    health_url: "http://127.0.0.1:8000/healthz"

Django

checks:
  runtime_smoke:
    enabled: true
    command: "python manage.py runserver 8000"
    health_url: "http://127.0.0.1:8000/health/"

Flask

checks:
  runtime_smoke:
    enabled: true
    command: "flask run --port 8000"
    health_url: "http://127.0.0.1:8000/health"

Using in CI

GitHub Actions

- name: Install VibeGate
  run: pipx install "vibegate[tools]"

- name: Run quality gate
  run: vibegate run .

Exit codes:

• 0 = PASS (all checks passed)
• 1 = FAIL (blocking issues found)
• 2 = CONFIG ERROR (invalid configuration)

Suppressing Findings

You can suppress specific findings in .vibegate/suppressions.yaml:

schema_version: v1alpha1
suppressions:
  - fingerprint: "sha256:abc123..."
    rule_id: "B404"
    justification: "subprocess.run() is safe here - input is validated"
    expires_at: "2025-12-31T00:00:00Z"
    actor: "security-team"

Important: Suppressions affect CI/CD behavior (suppressed findings don't cause failures).

For quality tracking (without affecting CI), use labels instead:

vibegate label sha256:abc123... --false-positive --reason "type-annotation-context"

Labels help tune checks over time but don't suppress findings.

Profiles

Use profiles to switch between different configurations:

profile: "strict"

profiles:
  fast:
    checks:
      tests:
        enabled: false

  strict:
    checks:
      sast:
        enabled: true
        severity_threshold: high

  ci:
    checks:
      runtime_smoke:
        enabled: true

Plugin System

VibeGate supports custom checks via plugins. See examples/hello-plugin/ for a complete example.

1. Install plugin: pip install -e examples/hello-plugin
2. Enable in config:

   plugins:
     checks:
       enabled:
         - hello
   

3. Run: vibegate run .

Self-Hosting: VibeGate Validates Itself

VibeGate uses itself to enforce quality standards.

Metric	Status
VibeGate Check	✅ PASS
Empty Except Blocks	✅ 0
Zero Division Guards	✅ 0
Bounds Validation	✅ 0

This demonstrates that defensive programming checks are practical for real-world code.

Troubleshooting

Config validation fails

vibegate init . --force

This overwrites vibegate.yaml with fresh defaults.

Missing tools

vibegate doctor .

This shows which tools are missing and how to install them.

Help

vibegate --help
vibegate run --help

Development

Run tests

make test
make test-cov      # with coverage
make coverage      # HTML report

Run VibeGate on itself

make gate

Build and test release

./scripts/build_and_smoke.sh

Sharing a clean source bundle

Create a clean zip of the source code (excludes build artifacts, caches, and virtual environments):

make bundle

This creates dist/vibegate-source.zip (or dist/source-<sha>.zip if in a git repo) containing only the essential source files. Perfect for sharing the codebase without bloat.

What's included:

• All git-tracked files (if in git repo)
• Or: filesystem walk excluding .venv*/, dist/, build/, *.egg-info/, caches, and runtime outputs

What's excluded:

• Virtual environments (.venv*/)
• Build artifacts (dist/, build/, *.egg-info/)
• Caches (.pytest_cache/, .ruff_cache/, .mypy_cache/, __pycache__/)
• Runtime outputs (.vibegate/artifacts/, .vibegate/evidence/, .vibegate/ui/runs/, .vibegate/llm_cache/)
• macOS metadata (__MACOSX/, .DS_Store)

Release Workflow

Releases are fully automated using semantic-release based on Conventional Commits.

How it works:

1. Merge PRs with conventional commit messages (feat:, fix:, etc.)
2. semantic-release runs automatically on push to main
3. If releasable commits exist, it:
   • Determines next version
   • Updates CHANGELOG.md
   • Creates git tag
   • Publishes to PyPI via Trusted Publishing
   • Creates GitHub Release

Commit types:

• feat: → minor bump (0.1.0 → 0.2.0)
• fix: → patch bump (0.1.0 → 0.1.1)
• feat!: or BREAKING CHANGE: → major bump (0.1.0 → 1.0.0)

See docs/RELEASING.md for details.

License

MIT License - see LICENSE file.

Links

• GitHub: https://github.com/maxadamsky/VibeGate
• PyPI: https://pypi.org/project/vibegate/
• Issues: https://github.com/maxadamsky/VibeGate/issues
• Docs: https://github.com/maxadamsky/VibeGate/tree/main/docs