python-checkup 0.4.1

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

python-checkup

Fast, local-first Python code health checks with a single command.

A 0-100 health score for Python codebases. Runs Ruff, mypy, Bandit, Radon, Vulture, and deptry in parallel, scores six categories, and tells you what to fix first.

Quickstart

uvx python-checkup .

To see the full report in your browser:

uvx python-checkup . --web

To install persistently:

uv tool install python-checkup

Usage

# quick scan (Ruff + deptry only, ~3s)
uvx python-checkup . --profile quick

# full scan with all optional analyzers
uvx --from 'python-checkup[full]' python-checkup .

# only changed files vs a branch
uvx python-checkup . --diff main

# auto-fix what Ruff can, then rescan
uvx python-checkup . --fix

# filter categories
uvx python-checkup . --only quality,security
uvx python-checkup . --skip dead_code

# output formats
uvx python-checkup . --score          # just the number
uvx python-checkup . --json           # machine-readable
uvx python-checkup . --badge          # shields.io URL

# CI gate
uvx python-checkup . --fail-under 70

What it runs

Default profile:

Category	Tools
Code Quality	Ruff
Type Safety	mypy
Security	Bandit, Ruff S-rules
Complexity	Radon, Ruff C901
Dead Code	Vulture
Dependencies	deptry

Optional analyzers (install via extras):

Extra	Adds
vulns	OSV-backed dependency vulnerability scanning
secrets	detect-secrets
pyright	basedpyright as type backend
quality-extra	typos for spelling checks
mcp	MCP server support
full	all of the above

Scoring

Each category gets a 0-100 score. The overall score is a weighted average:

Category	Default Weight
Code Quality	25
Type Safety	20
Security	20
Complexity	15
Dead Code	10
Dependencies	10

When a category has no available analyzer, its weight redistributes proportionally to the rest.

Score	Label
75-100	Healthy
50-74	Needs work
0-49	Critical

See docs/scoring.md for the full methodology.

Configuration

Works without config. To customize, add to pyproject.toml:

[tool.python-checkup]
timeout = 60

[tool.python-checkup.weights]
quality = 25
types = 20
security = 20
complexity = 15
dead_code = 10
dependencies = 10

[tool.python-checkup.thresholds]
healthy = 75
needs_work = 50

[tool.python-checkup.ignore]
rules = ["S101"]
files = ["tests/**", "migrations/**"]

See docs/configuration.md for the full reference.

CI

Gate on score:

uvx python-checkup . --fail-under 70

GitHub Action:

- uses: nabroleonx/python-checkup@v1
  with:
    fail-under: 70

Also works as a pre-commit hook. See action.yml and .pre-commit-hooks.yaml.

MCP Server

Expose python-checkup to AI coding agents (Claude Code, Cursor, VS Code):

uvx --from 'python-checkup[mcp]' python-checkup mcp install --editor cursor

Registers five tools: python_checkup_diagnose, python_checkup_lint, python_checkup_typecheck, python_checkup_security, python_checkup_explain_rule.

See docs/mcp-server.md for details.

Plugins

Add custom analyzers via entry points:

[project.entry-points."python-checkup.analyzers"]
my-analyzer = "my_package:MyAnalyzer"

See docs/plugins.md for the full guide.

Docs

• docs/configuration.md -- weights, thresholds, ignore rules
• docs/scoring.md -- scoring methodology
• docs/mcp-server.md -- MCP server setup
• docs/plugins.md -- custom analyzer development
• docs/development.md -- contributing

Development

uv sync --all-extras
uv run pytest
uv run ruff check python_checkup tests
uv run mypy python_checkup

License

MIT