codehealth

A fallow-style static "codebase intelligence" pass for Python. fallow is TypeScript/JavaScript-only; there's no single equivalent for Python, so this composes one out of four best-in-class tools and merges their output into one deterministic JSON report with a health score and a pass/warn/fail verdict.

Capability	Tool
Dead / unused code	vulture
Dependency hygiene (unused / missing / transitive)	deptry
Circular dependencies	tach map + networkx
Complexity hotspots + maintainability	radon
Architecture-boundary violations	tach check (needs tach.toml)

Quick start (zero install)

The script carries its own dependencies via PEP 723 inline metadata, so uv builds an ephemeral environment on the fly:

uv run codehealth.py path/to/project            # human-readable summary
uv run codehealth.py path/to/project --json     # machine-readable report

Install as a command (optional)

uv sync                 # or: uv pip install -e .
codehealth . --json

Useful flags

Flag	Default	Purpose
--json	off	Emit only the JSON report on stdout
--min-confidence N	80	Vulture confidence floor
--cc-threshold N	11	Cyclomatic complexity = hotspot (radon rank C)
--mi-threshold N	10	Maintainability index floor
--fail-under N	—	Exit 1 if score < N (CI gate)
--skip a,b	—	Skip analyses: vulture,deptry,radon,tach
--exclude "glob,glob"	—	Extra excludes on top of sane defaults

Sensible excludes (.venv, site-packages, node_modules, build, caches, migrations, …) are applied automatically so third-party code never drowns out real findings.

CI gate

uv run codehealth.py src --fail-under 75 --json > codehealth.json

Exits non-zero if the score drops below 75 or any missing dependency is found.

Expose to Claude Code

Two ways, mirroring fallow's "CLI primary, MCP optional" design:

1. As a skill (recommended). Drop this whole folder into your skills dir (e.g. ~/.claude/skills/code-health/ or /mnt/skills/user/code-health/). SKILL.md tells the agent how to run it and interpret the JSON.
2. As an MCP server. Register mcp_server.py (exposes a code_health tool):

   {
     "mcpServers": {
       "codehealth": { "command": "uv", "args": ["run", "/abs/path/mcp_server.py"] }
     }
   }

Report shape

{
  "summary": { "health_score": 88, "verdict": "pass", "counts": { ... } },
  "dead_code": [ { "file", "line", "kind", "name", "confidence" } ],
  "dependencies": { "unused": [], "missing": [], "transitive": [], "misplaced_dev": [] },
  "circular_dependencies": [ ["pkg/b.py", "pkg/a.py", "pkg/b.py"] ],
  "complexity": { "hotspots": [ ... ], "low_maintainability": [ ... ] },
  "boundaries": { "ran": false, "violations": [] },
  "errors": []
}

Scope vs. fallow

This is fallow's static layer, not its paid runtime layer (hot/cold paths, production deletion confidence). Duplication detection is also out of scope here (add pylint --disable=all --enable=duplicate-code or jscpd if you want it).