Use cases

What you can actually do with it

Three high-stakes walkthroughs and a recipe for every command — each one backed by a runnable fixture in the repo, so every command and every line of output is real. Nothing here is staged.

Hero workflows

The two jobs this tool exists for — faster code review and verified context for AI agents — plus the classics.

Review a PR in minutes

Turn a big diff into a focused map: what changed, the blast radius, risk flags, and a clickable file:line on every reference.

review --base init --with review

Feed your agent the right context

A verified, task-scoped context pack — 97% fewer tokens than the whole repo, zero guessed edges — plus AGENTS.md wiring.

context --focus export --for-ai

The orphan monolith

Inherit an undocumented codebase and get a trustworthy map, a health grade, and a dead-code list in three commands.

visualize health check --dead-code

The audit deadline

Turn a layering policy into an enforced, call-graph-level control and commit deterministic diagrams as dated audit evidence.

check --layers --forbid visualize

The fearless refactor

Measure a change's blast radius before you make it, then fail the PR when a refactor introduces a new circular dependency.

impact json diff --fail-on-new-cycles

A recipe for every command

All eight subcommands build on the same deterministic graph. Each recipe below is a copy-paste starting point; run py-code-visualizer <command> --help for the full flag set.

review — a PR review report

Detect the functions changed vs a base ref, compute their blast radius, flag risks (hubs, new cycles, ambiguous calls near the change), and emit a focused report with a clickable file:line on every reference. → Full walkthrough.

$ py-code-visualizer review . --base origin/main $ py-code-visualizer review . --base origin/main --fail-above 50 # optional policy

context — verified context pack for AI agents

A small, task-scoped slice of the architecture centered on the functions you name (or the ones changed vs a git ref), selected under a token budget by personalized PageRank. → Full walkthrough.

$ py-code-visualizer context . --focus your_pkg.core.save --budget-tokens 4000 $ py-code-visualizer context . --from-git origin/main # focus on the PR's changes

init — set up only the automation you want

Opt in to exactly the profiles you need — review, readme, context, or gates — and nothing else. Generates the CI workflow(s), never overwrites files without --force, and records your choice in pyproject.toml.

$ py-code-visualizer init --list # see profiles; writes nothing $ py-code-visualizer init --with review,context # generate just these

visualize — a self-contained interactive map

Render the call graph as one HTML file (no CDN, works offline), or as Mermaid, JSON, C4, or SVG/PNG. Click any edge to see its file:line.

$ py-code-visualizer visualize ./your_project -o architecture.html $ py-code-visualizer visualize ./your_project -f mermaid # GitHub-safe diagram $ py-code-visualizer visualize ./your_project --churn # git heatmap overlay

readme — a self-healing diagram in your docs

Inject or update a Mermaid diagram between marker comments in any Markdown file. Deterministic, so a CI bot commits only when the architecture actually changed — no phantom diffs. Use --check as a drift gate.

$ py-code-visualizer readme ./your_project # updates README.md in place $ py-code-visualizer readme ./your_project --check # exit 1 if it would change

json — the canonical, diffable graph

Emit the schema pyvisualizer/graph@1 — the substrate for diff, check, impact, and AI tools. Relative paths, sorted, byte-identical across runs.

$ py-code-visualizer json ./your_project -o graph.json

diff — a PR-ready change report

Compare two JSON snapshots: added/removed functions and edges, new cycles, health delta. --fail-on-new-cycles makes it a gate. → Full walkthrough.

$ py-code-visualizer diff base.json head.json --fail-on-new-cycles

check — architecture-as-code gates

Enforce layering rules and cycle-freedom at the call-graph level (stricter than an import linter). Add --dead-code for an unreachable-function review list. → Full walkthrough.

$ py-code-visualizer check ./your_project --fail-on-cycles $ py-code-visualizer check ./your_project --layers api domain infra --forbid 'domain -> api' $ py-code-visualizer check ./your_project --dead-code

impact — blast radius before you refactor

Transitive callers and callees of a function, and how many modules they touch. → Full walkthrough.

$ py-code-visualizer impact your_pkg.core.save ./your_project

health — an A–F architecture grade

Score coupling, cycles, hub risk, orphans, and ambiguity into one defensible grade, with an optional SVG badge for your README. → Full walkthrough.

$ py-code-visualizer health ./your_project $ py-code-visualizer health ./your_project --badge health.svg

export — ground truth for your AI tools

Emit ARCHITECTURE.json + ARCHITECTURE.md so Cursor/Claude/Copilot ingest a verified graph instead of re-deriving structure (wrongly) from raw source. Point your agent at the graph, not the repo.

$ py-code-visualizer export --for-ai ./your_project

The through-line. Every command reads the same deterministic, AST-verified graph where every edge carries a file:line and ambiguous calls are flagged, never guessed. That's why the output can live in CI, in your README, in a PR gate, and in an audit trail at the same time.

← Back to home