Hallow: codebase intelligence for Python

Hallow is my open-source tool for understanding a Python codebase. One command reports dead code, duplication, circular dependencies, complexity and architecture boundary violations.

Why I wrote it

No single tool covered Python this way. You needed one tool for dead code, another for complexity, another for circular imports and another for duplication. Each had its own configuration and output format, and none knew about the others. None detected unused files or unused dependencies, or gave a project-level quality score. Hallow is inspired by fallow, which does this for JavaScript and TypeScript.

What it does

• Finds unused files, imports, functions, classes, variables and dependencies.
• Scores cyclomatic and cognitive complexity per function and gives the project a health score from 0 to 100.
• Detects duplicated code in four modes, from exact copies to renamed copies.
• Finds circular imports.
• Checks architecture boundaries.
• Scans for hardcoded secrets.
• Gates a pull request on only the findings that change introduces.
• Runs as an MCP server with 6 tools, so AI agents can use it.

It uses Python's built-in ast module, with no external parser. Output comes as JSON, SARIF, Markdown or terminal text. It knows about Django, Flask, FastAPI, pytest and Celery.

Getting it

The current release is 0.2.0, under the Apache 2.0 license. Install it from source at github.com/sarob/hallow. It is not on PyPI yet.