GitHub - Shaelz/codebase-visualize-skill: A reusable codebase-visualization skill for Claude Code and Codex.

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.

Quickstart

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.

Have your coding agent install it

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.

Install the reusable skill

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 -Force in PowerShell or --force in bash.
• Clean reinstall: delete the installed target first, then rerun without -Force or --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 user

bash ./scripts/install.sh --tool claude --scope user

Codex

.\scripts\install.ps1 -Tool codex -Scope user

bash ./scripts/install.sh --tool codex --scope user

First use

Keep 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

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/repo

What to expect after the first run

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

Which install path applies to you?

Alternate install paths

.\scripts\install.ps1 -Tool claude -Scope project -ProjectRoot C:\path\to\repo

bash ./scripts/install.sh --tool claude --scope project --project-root /path/to/repo

.\scripts\install.ps1 -Tool codex -Scope project -ProjectRoot C:\path\to\repo

bash ./scripts/install.sh --tool codex --scope project --project-root /path/to/repo

What the skill actually does

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.

Running it again later

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/repo

From 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/repo

Regenerate the map rather than hand-editing generated files.

Outputs and authority boundaries

codebase-visualize works with several distinct layers that should not be confused:

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.md
• docs/ai/CHANGE_SURFACES.md
• docs/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.

Current feature scope and limits

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

Important notes

Explicit invocation is the reliable path

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.

Generated maps are orientation aids

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.

Large repositories may need scope

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 .gitignore snippets

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/

Local validation

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 demo

npm 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:

Run the isolated copied-package behavioral eval corpus:

The 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:

Check that the generated demo graph and HTML map are populated and self-contained:

Smoke-check generated-map browser behavior with a lightweight DOM harness:

npm run check:interactions

Prove the canonical skill package runs independently from a disposable copied location:

Run the disposable PowerShell and bash installer contract matrix:

Run the optional generic live-target smoke check against a local repository:

$env:CODEBASE_VISUALIZE_LIVE_TARGET = "C:\path\to\repository"
npm run check:live

CODEBASE_VISUALIZE_LIVE_TARGET=/path/to/repository npm run check:live

For 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:

The 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.json
• fixtures/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+K opens the command palette.
• +, -, and 0 zoom the graph in, out, and back to 1x.
• G and T switch between graph and tree views.
• In graph view, F fits the graph, A centers the selected node, R toggles reference links, 1/2/3 switch graph modes, and arrow keys pan.

Supported environment evidence

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

Release status

v1.0.0 published 2026-06-09. Frozen validation evidence is in docs/releases/v1.0-validation-record.md.

Reference and contributor notes

• skills/codebase-visualize/SKILL.md: canonical reusable skill behavior
• docs/V1_RELEASE_PLAN.md: historical v1 roadmap pointer
• docs/design/v0-architecture.md: implementation architecture
• docs/design/v1-stack-decision.md: accepted evolve-not-rewrite stack decision and reconsideration triggers
• docs/design/v1-contract-decisions.md: accepted write-boundary, versioning, runtime-topology, and CSS-authority decisions
• docs/design/graph-view-v1-plan.md: completed historical graph-view feature plan
• evals/README.md: behavioral-eval contract and limits
• docs/releases/VALIDATION_RECORD_TEMPLATE.md: reusable M5/M6 evidence-record shape
• docs/releases/PUBLIC_RELEASE_CHECKLIST.md: anonymization boundary, sibling-grade GitHub settings, and publication order
• docs/releases/M5_VALIDATION_RECORD.md: sanitized local live-fire, hygiene, graph-size, and visual evidence
• docs/releases/M6_GITHUB_EXPOSURE_AUDIT.md: initial GitHub-hosted and publishable-history exposure inventory
• docs/releases/M6_HISTORY_REWRITE_PLAN.md: controlled, recoverable pre-public rewrite procedure
• docs/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 checkout
• docs/releases/M6_RELEASE_CANDIDATE_VALIDATION.md: exact private release-candidate validation evidence
• CHANGELOG.md: release-facing change history
• scripts/: 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.

License

MIT. See LICENSE.