🔍 repolens

X-ray any codebase in one command

One line in, one file out — an interactive architecture map, blast-radius explorer, health grade, security scan, and hotspot report for any repo, local or on GitHub.

uvx repolens-kit facebook/react    # ← that's the whole setup

or try it online, no install: lens.bigwinner.work — paste any public repo

One-liners

uvx repolens-kit .                 # analyze the repo you're standing in (zero install)
uvx repolens-kit pallets/flask     # analyze any GitHub repo by shorthand
uvx repolens-kit https://github.com/fastapi/fastapi
pipx run repolens-kit .            # same, via pipx
pip install repolens-kit && repolens .  # installs the `repolens` command

Every run prints a rich terminal summary and writes a single self-contained HTML file — D3 inlined, zero external requests, works offline, safe to email or attach to a PR. Your code never leaves your machine.

What you get

How the analysis works

repolens parses source with per-language extraction (30+ languages: Python, TypeScript/JavaScript, Go, Rust, Java, Kotlin, C/C++, C#, Ruby, PHP, Swift, Elixir, and more), then resolves imports to files inside the repo to build a real dependency graph:

• Python: from X import name expands to submodules, src/-layout packages resolve, if TYPE_CHECKING: blocks and function-body (deferred) imports are excluded — so the cycles it reports are cycles that actually bite at import time.
• JS/TS: relative paths, index.* resolution, require/dynamic import().
• Ambiguous names are settled by ranking (package roots beat stray same-named fixtures) instead of being dropped.

On top of the graph: blast radius (reverse-reachability per file), SCC cycle detection, layer classification, hub/coupling metrics, and a security ruleset tuned for precision. Everything is heuristic and fast — ~1 second for a 1,000-file repo — built for orientation, not for replacing a compiler.

Usage

repolens [target] [options]

target                 local path, owner/repo, or GitHub URL (default: .)

-o, --output FILE      HTML report path (default: <name>-repolens.html)
    --json [FILE]      dump the full analysis model as JSON (stdout if no FILE)
-x, --exclude PATTERN  extra exclude glob, repeatable (e.g. -x 'docs/**')
    --max-files N      cap analyzed files (default: 6000)
    --tarball          fetch GitHub repos as a snapshot streamed in memory —
                       ~10x faster, zero disk writes, but no churn/ownership stats
    --no-open          don't auto-open the report in a browser
    --no-html          terminal summary only
-q, --quiet            no terminal summary

As a library

from repolens import analyze

report = analyze("path/or/owner/repo")
print(report["health"]["grade"], report["repo"]["edges"])

In CI

pip install repolens-kit
repolens . --no-open --no-html --json report.json
python -c "import json,sys; sys.exit(json.load(open('report.json'))['health']['score'] < 70)"

Privacy

• Local analysis never touches the network.
• GitHub targets are shallow-cloned with your own git (and deleted afterward) — no tokens collected, no telemetry, nothing phoned home.
• The HTML report inlines D3, so opening it makes zero external requests.

Credits

repolens is a from-scratch Python reimagining of CodeFlow by Braedon Saunders — a lovely browser-only codebase visualizer. Same mission (stop guessing, start seeing), rebuilt as an installable CLI with a resolvable import graph, honest health scoring, git mining, and offline single-file reports.

License

MIT — see LICENSE.