Skip to content

python-checkup

Fast, local-first CLI that gives your Python codebase a 0-100 health score.

What is python-checkup?

python-checkup unifies the best Python static analysis tools into a single command:

  • Ruff -- 900+ lint rules for code quality
  • mypy -- strict type checking
  • Bandit + detect-secrets -- security vulnerability scanning
  • Radon -- cyclomatic complexity and maintainability index
  • Vulture -- dead code detection
  • OSV vulnerability scanning + deptry -- dependency vulnerability and hygiene checks

Quickstart

uvx python-checkup .

Or install persistently:

uv tool install python-checkup
python-checkup .

For all optional analyzers:

uvx --from 'python-checkup[full]' python-checkup .

Key Features

  • Zero-config -- works on any Python 3.10+ project out of the box
  • Density-based scoring -- per-KLOC metrics that scale fairly across project sizes
  • MCP server -- expose health data to AI coding agents (Claude Code, Cursor, VS Code)
  • Skill system -- install rules knowledge into AI agents
  • Framework detection -- auto-detects Django, FastAPI, Flask and activates extra rules
  • Caching -- content-hash caching for near-instant repeat scans
  • CI/CD -- GitHub Action, pre-commit hook, badge generation
  • Plugin system -- extend with custom analyzers via entry points

Next Steps

  • Configuration -- customize weights, thresholds, and ignored rules
  • Scoring -- understand the scoring methodology
  • MCP Server -- set up AI agent integration
  • Plugins -- extend with custom analyzers
  • Development -- contributing to python-checkup