PyCodeGate

Trust, but verify. The quality gate for AI-generated Python code.

Why PyCodeGate?

AI coding agents ship code fast — but fast doesn't mean safe. Every eval() an LLM drops in, every mutable default it forgets, every circular import it creates is a landmine waiting to go off. PyCodeGate is the trust layer between AI-generated code and your production codebase: one command, one score, zero ambiguity.

How it works

PyCodeGate detects your project's context: framework (Django, FastAPI, Flask), Python version, package manager (uv, poetry, pip), and test framework. That context drives which rules are active — Django projects get SQL injection checks, FastAPI projects get async-correctness checks, and so on.

It then runs two analysis passes in parallel: a lint pass that evaluates 40+ rules across 8 categories (Security, Correctness, Complexity, Architecture, Performance, Structure, Imports, Dead Code), and a dead-code pass powered by Vulture that finds unused functions, classes, imports, and variables.

Findings are filtered through your configuration and scored using a weighted category-budget system. Each category has a maximum deduction budget proportional to its weight. Within a category the top 3 findings apply at full cost; additional findings apply diminishing returns (10% each), so fixing the worst issues always moves the needle. The final result is a 0–100 health score with a label: Excellent (90+), Great (75–89), Needs work (50–74), or Critical (<50).

Install

Run instantly with uvx — no install needed:

uvx pycodegate .

Install globally with pipx or uv:

pipx install pycodegate
# or
uv tool install pycodegate
# or
pip install pycodegate

Quick Start

# Basic scan — score + summary
pycodegate .

# Show file paths and line numbers for every finding
pycodegate . --verbose

# Machine-readable output for AI agents and CI
pycodegate . --json

# Auto-fix ruff-fixable issues, then scan
pycodegate . --fix

# Output only the numeric score (useful in scripts)
pycodegate . --score

# Scan only files changed vs a base branch
pycodegate . --diff main

JSON Output

Pass --json to get structured output that AI agents and CI pipelines can parse:

pycodegate . --json

{
  "version": "0.1.0",
  "path": ".",
  "score": 87,
  "label": "Great",
  "errors": 1,
  "warnings": 4,
  "elapsed_ms": 212,
  "project": {
    "framework": "fastapi",
    "python_version": "3.12",
    "package_manager": "uv",
    "test_framework": "pytest"
  },
  "diagnostics": [
    {
      "rule": "no-mutable-default",
      "severity": "error",
      "category": "Correctness",
      "message": "Mutable default argument `[]` is shared across all calls",
      "file_path": "src/api/routes.py",
      "line": 34
    },
    {
      "rule": "high-complexity",
      "severity": "warning",
      "category": "Complexity",
      "message": "Function 'process_order' has cyclomatic complexity 17 (max 15)",
      "file_path": "src/api/orders.py",
      "line": 88
    }
  ]
}

Agent Integration

PyCodeGate is designed to be used by AI coding agents. Add it to your agent's context so it runs after every Python change.

Claude Code

Add the skill to your project:

mkdir -p .claude/skills
curl -fsSL https://raw.githubusercontent.com/themohitkhare/pycodegate/main/skills/pycodegate/SKILL.md \
  -o .claude/skills/pycodegate.md

Or copy AGENTS.md to your project root — Claude Code picks it up automatically.

Cursor

Add to .cursor/rules/pycodegate.mdc:

After modifying Python files, run `uvx pycodegate . --json` and fix all findings
with severity "error" before marking the task complete. Target score: 80+.

Windsurf

Add to .windsurfrules:

After modifying Python files, run: uvx pycodegate . --json
Fix all "error" severity findings. Re-run to verify the score improved.

Codex

Add to your system prompt:

After modifying Python files, run `uvx pycodegate . --json` to check code quality.
Fix errors first. Target score: 80+.

Aider

aider --read AGENTS.md

GitHub Actions

name: Quality Gate

on: [push, pull_request]

jobs:
  pycodegate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # required for --diff

      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Run PyCodeGate
        run: |
          pip install pycodegate
          pycodegate . --verbose --diff main --fail-on error

CLI Reference

What It Checks

Framework-specific rules (Django, FastAPI, Flask) are mapped into the Security or Correctness budget.

Scoring

PyCodeGate uses a weighted category-budget system:

1. Each category has a weight (see table above). Weights are normalized to sum to 100 points of total deduction budget.
2. Within a category, findings are sorted by cost (errors cost more than warnings). The top 3 findings apply at full cost; every additional finding applies diminishing returns (10% of its cost).
3. A category's deduction is capped at its budget, so a single broken category can never zero out an otherwise healthy project.
4. Final score = 100 - sum(capped category deductions), floored at 0.

Configuration

Create pycodegate.toml in your project root:

[options]
lint = true
dead_code = true
verbose = false
fail_on = "none"

[ignore]
rules = ["dead-code", "no-import-in-function"]
files = ["tests/fixtures/**", "migrations/**", "scripts/**"]

[per-file-ignores]
"src/legacy/*.py" = ["high-complexity", "no-god-function"]

[scoring]
max-deduction.Security = 20
max-deduction.Dead Code = 0  # disable dead-code penalty entirely

Or use pyproject.toml:

[tool.pycodegate]
lint = true
dead_code = true
fail_on = "error"

[tool.pycodegate.ignore]
rules = ["no-import-in-function"]
files = ["tests/fixtures/**"]

[tool.pycodegate.per-file-ignores]
"src/legacy/*.py" = ["high-complexity"]

[tool.pycodegate.scoring]
"max-deduction" = { Security = 20, "Dead Code" = 0 }

If both files exist, pycodegate.toml takes precedence. CLI flags always override config values.

Profiles

PyCodeGate auto-detects a project profile and adjusts rule weights accordingly. You can also set a profile explicitly in config (profile = "library").

Pre-commit Hook

Use --pre-commit to run PyCodeGate as a pre-commit hook. It automatically scans only the staged files:

pycodegate . --pre-commit --fail-on error

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: pycodegate
        name: PyCodeGate quality check
        entry: pycodegate . --pre-commit --fail-on error
        language: system
        types: [python]
        pass_filenames: false

Contributing

git clone https://github.com/themohitkhare/pycodegate
cd pycodegate
uv sync --all-extras
uv run pytest -q
uv run pycodegate . --verbose  # dogfood it

To add a new rule:

1. Create a file in src/pycodegate/rules/ extending BaseRules
2. Implement check(self, source: str, filename: str) -> list[Diagnostic]
3. Register it in src/pycodegate/rules/__init__.py
4. Add tests in tests/rules/

License

MIT