codebase-visualize is a reusable skill for Claude Code and Codex that turns a target repository into a structured graph JSON file and a self-contained interactive HTML map for agent orientation.
Instead of asking a model to vaguely "look around", this skill gives the agent a visual and operational map: where things live, which files look important or risky, what references point where, what is still unknown, and what to read before editing a given area. It is a sibling/companion to codebase-orient: orient writes narrative repo orientation docs; visualize writes generated map artifacts under its own namespace.
Note
Installing a skill copies skill files into your tool's skill directory only. Running codebase-visualize against a target repo creates or refreshes only docs/ai/visualize/codebase-graph.json and docs/ai/visualize/codebase-map.html in that target. Those outputs are generated, refreshable orientation aids, not source of truth. The v1 scanner uses filesystem facts plus lightweight heuristics; it does not perform AST, import, or dependency analysis. v1.0.0 is the first stable release. See the release for validation evidence and install instructions.
Most users want the reusable codebase-visualize skill at the user level for the tool they already use.
Before running the install scripts, clone or download this repository locally and run the commands below from the repository root so scripts/ is present.
If you already work in Codex or Claude Code, a practical onboarding path is to give that coding agent this repository and ask it to install the reusable skill for the tool you are currently using.
Exact-install integrity rule for agent-delegated setup:
- The agent must first obtain an exact local copy of the requested repo revision by cloning/checking out the requested tag or by downloading and extracting that tagged archive.
- It must then run the checked-in installer script for the selected tool and install scope.
- It must not manually recreate, paste, summarize, paraphrase, or rewrite skill files from web-fetched, rendered, transformed, or partial content.
- If it cannot obtain an exact local copy or cannot run the documented installer, it must stop and ask rather than approximate the installation.
- It must report how to invoke the installed skill explicitly, but must not visualize any repository until you choose the target.
Use this prompt:
Install the reusable codebase-visualize skill for the coding tool we are using now. Follow this repository's README. Obtain an exact local copy of the requested repo revision first by cloning/checking out the requested tag or by downloading and extracting that tagged archive, then run the checked-in installer script. Do not manually recreate or rewrite skill files from fetched or rendered content. Use the recommended user-level install path by default unless I request project-local scope; if I ask to install it "in this project," use the supported project-local route. If an installation already exists, do not overwrite or delete it automatically; explain the choices and ask me whether to do an overlay refresh, a clean reinstall, or a project-local install instead. After installation, report how to invoke the installed skill explicitly. Do not visualize any target repository until I choose the target or ask you to do that next.
The manual commands below remain the inspectable install contract that the agent should follow.
| If you use | Recommended install | What it changes |
|---|---|---|
| Claude Code | User-level codebase-visualize |
Copies the skill to ~/.claude/skills/codebase-visualize/ |
| Codex | User-level codebase-visualize |
Copies the skill to ~/.agents/skills/codebase-visualize/ |
If you want a project-local install instead, skip to Alternate install paths before running the default commands below.
If the install target already exists, stop and choose intentionally:
- Overlay refresh: rerun with
-Forcein PowerShell or--forcein bash. - Clean reinstall: delete the installed target first, then rerun without
-Forceor--force. - Project-local install: use this when you intentionally want repo-scoped installation or testing.
- Agents acting on your behalf should ask before overwriting an existing installation.
Claude Code
.\scripts\install.ps1 -Tool claude -Scope usermacOS/Linux
bash ./scripts/install.sh --tool claude --scope userCodex
.\scripts\install.ps1 -Tool codex -Scope usermacOS/Linux
bash ./scripts/install.sh --tool codex --scope userKeep these three steps separate:
- Installing the skill copies files into the tool's skill location.
- Invoking the installed skill is the next step.
- Visualizing a target repo happens only after you explicitly invoke the skill and choose that target.
Reading an installed SKILL.md or checking copied files can confirm what was installed, but that is not the same as confirming the tool discovered or invoked the installed skill. After installing, Codex should detect a newly installed or updated skill automatically. If codebase-visualize does not appear, restart Codex.
Then invoke the skill explicitly and ask it to visualize the target repo.
Claude Code
/codebase-visualize
Codex
In Codex CLI or the IDE extension, run `/skills` or type `$` to mention/select `codebase-visualize`, then ask it to visualize the chosen repo. In the Codex app, the skill is also available, but this README does not assume the same picker interaction there unless Codex documentation says so.
The underlying installed command is:
node <skill-dir>/scripts/visualize.mjs --target /path/to/repoRunning the skill refreshes both generated artifacts:
<target>/docs/ai/visualize/codebase-graph.json<target>/docs/ai/visualize/codebase-map.html
Open codebase-map.html directly in a browser. Start with the tree/sidebar, switch to graph view for focused structure, use search/filter for specific paths, and use Copy agent briefing when handing context to another agent or teammate.
If the map reports a large repository, many unknowns, or sparse references, treat that as scoping guidance rather than failure.
| Path | Use it when | Target |
|---|---|---|
User-level codebase-visualize |
You want one reusable skill available across projects in the same tool | ~/.claude/skills/codebase-visualize/ or ~/.agents/skills/codebase-visualize/ |
Project-local codebase-visualize |
You want the skill available only inside one repo | .claude/skills/codebase-visualize/ or .agents/skills/codebase-visualize/ |
| Source checkout | You are developing or validating this skill itself | This repository |
Project-local install for Claude Code or Codex
Run the installer from the skill source checkout and pass the target project path. The scripts install into the target project and do not edit .gitignore.
Claude Code project-local
.\scripts\install.ps1 -Tool claude -Scope project -ProjectRoot C:\path\to\repobash ./scripts/install.sh --tool claude --scope project --project-root /path/to/repoThis copies the skill into .claude/skills/codebase-visualize/ in the target repo.
Codex project-local
.\scripts\install.ps1 -Tool codex -Scope project -ProjectRoot C:\path\to\repobash ./scripts/install.sh --tool codex --scope project --project-root /path/to/repoThis copies the skill into .agents/skills/codebase-visualize/ in the target repo.
If a project-local installed skill should remain untracked, add the matching directory to that target repo's .gitignore yourself.
The canonical skill source is skills/codebase-visualize/SKILL.md. Its job is useful codebase cartography for AI coding agents, not decorative diagrams.
It tells the agent to:
- scan a target repository directory;
- skip dependency, build, cache, and local agent/tool scratch folders;
- classify files and folders with coarse kinds such as docs, tests, config, scripts, source, styles, assets, and unknown;
- attach simple risk and change-surface hints such as config, lockfile, migration/schema, route-looking, test, generated docs, and orient docs;
- emit factual folder containment edges plus inferred Markdown file-reference edges;
- report skipped symlinks and unreadable filesystem entries in
metadata.scan_warnings; - render a single self-contained HTML map with overview counts, domains, important nodes, search, filters, tree/graph views, details, routing hints, a legend, large/low-signal notices, and a copyable agent briefing;
- label every claim as fact, inference, or unknown.
It is meant for broad or unfamiliar work, repo handoffs, pre-refactor orientation, and follow-up work where a visual map is cheaper than rediscovering the repo from scratch.
Use the same invocation whenever docs/ai/visualize/ is missing, stale, or likely cheaper than rediscovering the repo structure.
node <skill-dir>/scripts/visualize.mjs --target /path/to/repoFrom an installed or copied skill package you can also run the split commands:
node <skill-dir>/scripts/scan.mjs --target /path/to/repo
node <skill-dir>/scripts/render.mjs --target /path/to/repoRegenerate the map rather than hand-editing generated files.
codebase-visualize works with several distinct layers that should not be confused:
| Layer | Owns | Source of truth? |
|---|---|---|
skills/codebase-visualize/ in this repo |
Canonical reusable skill package, runtime scripts, and renderer assets | Yes, for this skill |
Installed codebase-visualize package |
Local runtime copy used by Claude Code or Codex | No, reinstall from canonical source when it drifts |
Target repo docs/ai/visualize/* |
Generated graph JSON and HTML map | No, refreshable output only |
Target repo docs/ai/CODEBASE_MAP.md, CHANGE_SURFACES.md, OPEN_QUESTIONS.md |
Sibling codebase-orient narrative orientation docs |
No, but owned by codebase-orient, not this skill |
| Target repo source code and config | The actual project behavior | Yes, for the target project |
The enforced namespace contract is that codebase-visualize owns only docs/ai/visualize/ inside a target repo.
The sibling codebase-orient owns the root orientation docs:
docs/ai/CODEBASE_MAP.mddocs/ai/CHANGE_SURFACES.mddocs/ai/OPEN_QUESTIONS.md
The visualizer treats those orientation docs as read-only. If they are present in a scanned repo they appear as normal graph nodes with an orient-docs risk hint. The scanner also uses their explicit path mentions as inferred reference edges when those paths resolve to files that are already in the graph.
The v1 implementation proves one loop end-to-end. The core loop, frozen graph schema 1.0.0, adversarial safety suite, local checks, real-repo smoke check, and desktop/mobile visual checks are working.
Not in scope for v1:
- No AST or language parsing.
- No MCP integration.
- No Excalidraw or other diagram-tool export.
- No dependency on
codebase-orient. - No plugin framework or config system.
- No runtime web dependencies.
- No CI/GitHub Actions.
- No review bundles.
The current implementation proves one loop:
target repo -> graph JSON -> interactive HTML -> useful agent-routing hints
The skill may be auto-invoked when the model recognizes a visualization request, but auto-invocation is model-driven and not guaranteed. If you want the map, invoke codebase-visualize explicitly.
The files under docs/ai/visualize/ are generated and refreshable. Classifications, risk hints, and reference edges are heuristic. Do not treat the graph as an authoritative dependency map; there is no real import analysis.
The HTML map includes large-repo and low-signal notices. If the map warns about size, unknowns, or sparse references, scope the target to the relevant package or area before relying on the map for planning.
Project-local installation does not edit .gitignore. If you install a project-local skill and want to keep the installed package untracked, add the matching pattern yourself.
Claude Code
.claude/skills/codebase-visualize/Codex
.agents/skills/codebase-visualize/Node.js 18+ is required. The installed runtime uses only Node.js standard-library modules. Repository checks currently require npm install.
The source repository provides development wrappers:
npm run scan -- --target /path/to/repo
npm run render -- --target /path/to/repo
npm run demonpm run demo scans and renders the bundled fixture repo with the shipped canonical renderer CSS. It does not rebuild the CSS asset implicitly.
Run the full local validation loop:
npm run checkRun the isolated copied-package behavioral eval corpus:
npm run check:evalsThe eval suite grades structured graph evidence across backend, frontend, documentation-heavy, ambiguous, and sibling-operation fixtures. It is deterministic and offline; it does not replace visual, live-fire, platform, or cold-user validation.
Check that tracked text is ASCII-only:
npm run check:asciiCheck that the generated demo graph and HTML map are populated and self-contained:
npm run check:renderSmoke-check generated-map browser behavior with a lightweight DOM harness:
npm run check:interactionsProve the canonical skill package runs independently from a disposable copied location:
npm run check:packageRun the disposable PowerShell and bash installer contract matrix:
npm run check:installersRun the optional generic live-target smoke check against a local repository:
$env:CODEBASE_VISUALIZE_LIVE_TARGET = "C:\path\to\repository"
npm run check:liveCODEBASE_VISUALIZE_LIVE_TARGET=/path/to/repository npm run check:liveFor a sanitized multi-target evidence summary, point CODEBASE_VISUALIZE_LIVE_CONFIG at a local JSON file containing generic labels and target paths, then run npm run collect:live. Raw artifacts and paths must remain outside tracked source.
Check the tracked current tree for private validation target names and concrete workstation paths:
npm run check:publicThe separate npm run check:public:history command audits publishable branch and tag history, including content, filenames, messages, and commit identity. npm run check:public:contracts proves the history gate rejects historical filename and identity leaks.
The demo produces:
fixtures/sample-repo/docs/ai/visualize/codebase-graph.jsonfixtures/sample-repo/docs/ai/visualize/codebase-map.html
Open the HTML file directly in a browser. No server or build step is required.
The map includes keyboard shortcuts for common navigation:
Ctrl+Kopens the command palette.+,-, and0zoom the graph in, out, and back to 1x.GandTswitch between graph and tree views.- In graph view,
Ffits the graph,Acenters the selected node,Rtoggles reference links,1/2/3switch graph modes, and arrow keys pan.
- Windows PowerShell, Git Bash, and WSL2 Ubuntu are locally verified.
- WSL2 validation used Linux-native Node.js and covered adversarial inputs, copied-package behavior, package independence, and the bash installer matrix.
- macOS is currently unverified.
v1.0.0 published 2026-06-09. Frozen validation evidence is in
docs/releases/v1.0-validation-record.md.
skills/codebase-visualize/SKILL.md: canonical reusable skill behaviordocs/V1_RELEASE_PLAN.md: historical v1 roadmap pointerdocs/design/v0-architecture.md: implementation architecturedocs/design/v1-stack-decision.md: accepted evolve-not-rewrite stack decision and reconsideration triggersdocs/design/v1-contract-decisions.md: accepted write-boundary, versioning, runtime-topology, and CSS-authority decisionsdocs/design/graph-view-v1-plan.md: completed historical graph-view feature planevals/README.md: behavioral-eval contract and limitsdocs/releases/VALIDATION_RECORD_TEMPLATE.md: reusable M5/M6 evidence-record shapedocs/releases/PUBLIC_RELEASE_CHECKLIST.md: anonymization boundary, sibling-grade GitHub settings, and publication orderdocs/releases/M5_VALIDATION_RECORD.md: sanitized local live-fire, hygiene, graph-size, and visual evidencedocs/releases/M6_GITHUB_EXPOSURE_AUDIT.md: initial GitHub-hosted and publishable-history exposure inventorydocs/releases/M6_HISTORY_REWRITE_PLAN.md: controlled, recoverable pre-public rewrite proceduredocs/releases/M6_REWRITE_DRY_RUN_RECORD.md: sanitized proof that the controlled rewrite preserves the tip tree and passes publishable-history checks in a fresh checkoutdocs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md: exact private release-candidate validation evidenceCHANGELOG.md: release-facing change historyscripts/: install, demo, and validation helpers
Tracked repo-maintenance text in this repo follows an ASCII punctuation convention. Run npm run check:ascii before release-facing commits.
MIT. See LICENSE.