# Codebase Visualize

> Use to build a visual + operational map of a repository for an AI coding agent. Scans a target repo into a structured graph JSON and renders a self-contained interactive HTML map, with claim labels (fact / inference / unknown), risk hints, and an agent routing panel that suggests what to read before editing a file or domain. Good triggers: visualize this codebase, map the repo, show me the structure, what should I read before editing X, where do things live, generate a codebase map/graph. Does NOT do AST/import analysis, MCP, or diagram-tool export.

- Skill: `shaelz/codebase-visualize` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add shaelz/codebase-visualize`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shaelz/codebase-visualize/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: Shaelz (https://skillmd.com/u/shaelz)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shaelz/codebase-visualize

---


# 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:
   ```bash
   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`

2. **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.

3. **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:

```bash
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

| File | What it is |
| --- | --- |
| `docs/ai/visualize/codebase-graph.json` | Nodes (files/folders), edges (contains + references), and metadata. |
| `docs/ai/visualize/codebase-map.html` | Self-contained interactive viewer (inline CSS/JS). |

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:

| Path | Owner | Visualizer access |
| --- | --- | --- |
| `docs/ai/visualize/codebase-graph.json` | codebase-visualize | read + write |
| `docs/ai/visualize/codebase-map.html` | codebase-visualize | read + write |
| `docs/ai/CODEBASE_MAP.md` | codebase-orient | read-only advisory |
| `docs/ai/CHANGE_SURFACES.md` | codebase-orient | read-only advisory |
| `docs/ai/OPEN_QUESTIONS.md` | codebase-orient | read-only advisory |

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."

```bash
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.