/codegraph

name: codegraph
description: Turn any codebase into an explorable interactive graph so a developer can understand it fast. Deterministic scan (files, imports, symbols, call edges, PageRank importance, architectural layers, dependency cycles, entry points) plus optional AI enrichment (plain-English summaries and guided tours), delivered as ONE self-contained HTML file. Use when asked to explain, map, visualize, diagram, onboard onto, or understand a repository or its architecture.
author: SylphAI-Inc
version: 1.0.0

codegraph

Turn a codebase into a map a human can actually read.

**The goal is not a graph that shows off how complex the code is — it is a graph that quietly teaches someone how the pieces fit together.**

When to Use

Trigger on requests like:

• "help me understand this codebase" / "I just joined this project"
• "map / visualize / diagram this repo or its architecture"
• "what are the entry points?" / "how does data flow through this?"
• "generate an onboarding guide" / "where do I start reading?"
• "show me the dependency graph" / "find circular dependencies"
• "which files are most important here?"

Do **not** use this for a single-file explanation — just read the file.

Core Design (read this before running anything)

Three stages. Two are deterministic; only the middle one uses your intelligence.

1. scan.py    codebase  ->  graph.json + digest.md     deterministic, no LLM, no network
2. YOU        digest.md ->  enrich.json                 summaries, layer fixes, tours
3. render.py  both      ->  codegraph.html              one portable self-contained file
              (overview.py collapses the graph into the overview diagram en route)

Why this split matters — **do not violate it**:

| Stage | Owner | Guarantee | |---|---|---| | Structure (files, imports, calls, metrics, cycles) | `scan.py` | Reproducible. Same commit always yields the same edges. | | Meaning (what a file is *for*, tours) | You | Only a model can write this. | | Delivery (layout, validation, HTML) | `render.py` | Validated before write; a broken artifact never replaces a good one. |

**Never hand-write `graph.json`.** It is machine output. You only ever write `enrich.json`. **Never invent files, symbols, or relationships.** Every id you emit must already exist in the digest.

Instructions

Step 1 — Scan (always start here)

python3 <skill>/scripts/scan.py <repo> -o <repo>/.codegraph

Nothing to install: Python 3.8+ stdlib only. ~2s for 230k LOC.

Useful flags:

• `--max-files N` (default 4000) — raise it if output warns about truncation
• `--symbols-for N` (default 250) — extract function/class nodes for the N most important files
• `--no-calls` — skip heuristic cross-file call edges (faster, fewer false positives)

Then **read `digest.md`, not `graph.json`.** The digest is a compact briefing (entry points, directory map, ranked-importance table, cycles, dependencies, layer counts). `graph.json` can be megabytes and will flood your context for no benefit.

Step 2 — Enrich (this is your real work)

Write `<repo>/.codegraph/enrich.json`:

{
  "project": { "description": "1-3 sentences: what this codebase IS and does." },
  "nodes": {
    "file:src/server.ts": {
      "summary": "HTTP entry point. Wires middleware, mounts routers, starts the listener.",
      "layer": "entry",
      "tags": ["bootstrap", "http"]
    }
  },
  "layers": { "service": "Domain logic; no HTTP or SQL touches this layer." },
  "tours": [
    {
      "title": "Request lifecycle",
      "description": "Follow one HTTP request end to end.",
      "steps": [
        { "nodeId": "file:src/server.ts", "note": "Request arrives; middleware chain runs here." },
        { "nodeId": "file:src/routes/user.ts", "note": "Routing picks a handler." }
      ]
    }
  ]
}

Rules: 1. **Node ids must come from the digest verbatim** (`file:...`, `mod:...`, `sym:...`, `ext:...`). Unknown ids are dropped with a warning — silent quality loss. 2. **Summarize the top ~30-60 ranked files first.** Full coverage of a large repo is rarely worth the tokens; importance ordering already tells you what matters. 3. Write **what it is + why it exists**, not a restatement of the filename. Bad: "Utils file with utilities." Good: "Retry/backoff helpers shared by every outbound API client." 4. **Fix wrong layers.** `scan.py` guesses from paths and says so. If `core/` is really data access, override it. 5. **At least one tour, 3-6 steps.** Tours are the single highest-value output for onboarding — they encode reading *order*, which a graph alone cannot. 6. Read actual source before summarizing important files. Do not infer from names alone.

Scale guidance: read the top files in batches, and prefer breadth (many short, correct summaries) over depth (a few essays).

Step 3 — Render and verify

python3 <skill>/scripts/render.py --in <repo>/.codegraph --open

• Validates first; on failure it prints exact reasons and writes nothing.
• `--validate-only` to check without writing; `--strict` to fail on warnings.
• Output: `<repo>/.codegraph/codegraph.html` — one file, no CDN, works offline, safe to commit or send.

Always report to the user: node/edge counts, how many summaries and tours landed, and the artifact path.

What the artifact gives the reader

**Three linked views in one file**, cycled with `Tab`:

1. **overview** — architecture diagram (module boxes on layer bands, flowing connectors, a comet on the primary dependency path). Answers *"what are the parts?"* 2. **star map** — the same modules as an **orbitable** galaxy field, brightness = importance (Physics-atlas idiom: hot cores, double halos, diffraction spikes). Answers *"where is the weight of this system?"* **Drag to orbit · scroll to dolly · shift-drag to pan · `0` to reset**, with damped inertia and a slow idle auto-rotate — the same interaction contract as the atlas' `OrbitControls`, implemented as a projected 2.