codebase-visualize

Turn a target repository into two refreshable artifacts:

1. docs/ai/visualize/codebase-graph.json - a structured graph (nodes + edges + metadata)
2. docs/ai/visualize/codebase-map.html - a self-contained interactive map (no build step)

The point is operational cartography for agents: where things live, what is risky to touch, and what to read before editing - not pretty diagrams.

When to use this skill

Use it when:

• You (or another agent) are new to a repo and need a fast structural overview.
• Someone asks "visualize / map this codebase" or "where does X live".
• Before broad or multi-file changes, to see change surfaces and risk hints.
• You want an "agent routing" hint: what should I read before editing this area?

Skip it for tiny, well-understood single-file changes.

Workflow

The skill package is self-contained. Installation is separate from invocation; resolve <skill-dir> to the installed or copied codebase-visualize directory before running these commands.

1. Visualize the target repo:

   node <skill-dir>/scripts/visualize.mjs --target /path/to/repo

This scans, then renders. It writes only:

• <target>/docs/ai/visualize/codebase-graph.json
• <target>/docs/ai/visualize/codebase-map.html

1. Open the HTML file in a browser. Use the sidebar (domains), search box,

tree/graph switch, map-signal notices, copy agent briefing action, and detail panel. Read the agent routing suggestions for the selected node.

1. Regenerate rather than hand-edit. The artifacts are snapshots. Re-run

visualize.mjs --target /path/to/repo after the target repo changes.

Optional split commands:

node <skill-dir>/scripts/scan.mjs --target /path/to/repo
node <skill-dir>/scripts/render.mjs --target /path/to/repo

Use scan to refresh only the graph JSON. Use render when the graph JSON already exists and you only need to rebuild the HTML map.

In the source repository, npm run demo runs both steps against the bundled fixture.

Generated outputs

Graph metadata includes: generated_at, target_root, scanner_version, ignored_patterns, scan_warnings, counts, and a claim_policy.

Namespace and ownership contract

The intended default skill operation owns only docs/ai/visualize/* inside a target repo.

The sibling codebase-orient-skill owns the root orientation docs:

Rules:

• Public commands accept only --target and write only the fixed paths under

docs/ai/visualize/.

• If orientation docs are present in a scanned repo, they appear as normal graph

nodes with kind docs and risk hint orient-docs. The scanner does not read their content to enrich routing hints (planned for a future version).

• If orientation docs are absent, the visualizer works correctly from

deterministic filesystem scans alone.

• Both tool families may coexist in the same repo without conflict.

Claim labels

Every classification in the graph carries a claim label so consumers know how much to trust it:

• fact - directly observed (path, name, extension, size, folder hierarchy).
• inference - heuristic guess from naming/extension (e.g. "looks like a route",

"looks like a migration"). May be wrong.

• unknown - not enough signal to classify; treat as unexplored.

These three values are the claim_policy object embedded in every generated graph's metadata and schema-validated before rendering. The HTML legend explains them, and risk hints are shown per node. Large-repo, sparse-reference, and many-unknown notices are usability guidance, not hard failures. Scope the target to a subdirectory if the graph feels too busy.

Safety / authority boundaries

• Outputs are generated and refreshable, not canonical truth.
• There is no real dependency/import analysis - do not treat edges as a call graph.
• Risk hints are heuristics; verify against the actual code before acting.
• The scanner reads the target. Public commands write only inside

<target>/docs/ai/visualize/.

• Symlinks are reported and skipped rather than traversed. Unreadable

directories, files, and Markdown are reported in metadata.scan_warnings.

• The renderer accepts graph schema major version 1, validates required

fields and relationships before rendering, and rejects malformed graphs without replacing an existing map.

• Repository-controlled filenames and Markdown evidence are embedded as data,

not executable markup. Reference evidence text is bounded.

• Do not hand-edit generated files; re-scan instead.

Out of scope through v1

No AST parsing, no MCP, no Excalidraw export, no dependency on codebase-orient-skill, no heavy dependencies, no CI.

Example invocation

"Visualize the codebase at ./fixtures/sample-repo and tell me what I should read before editing the API routes."

node <skill-dir>/scripts/visualize.mjs --target /path/to/repo
# then open /path/to/repo/docs/ai/visualize/codebase-map.html

Select a route-looking file in the map; the agent routing panel lists the sibling files, configs, and docs to read first.