English | 简体中文

codeblast parses your repository into a deterministic code graph and answers the three most expensive questions around any code change:

🔗 Live interactive demo — real architecture maps of tRPC / Tabby / sgp, with three-level drill-down

	Question	Command
🎯	What breaks if I change this?	impact — direct / transitive / affected-tests, in three tiers
🔍	What did this PR structurally change?	change — symbols and dependency edges added, removed, renamed
🗺️	What does this project look like?	archmap — collapsible module map + circular-dependency detection

Built for humans (CLI / interactive HTML / PR comments) and for AI agents (SKILL.md) — one graph, two front-ends.

Impact overlay — blast radius on the map (tRPC · live ↗)

Architecture map — hover lights the dependency fan-in (Tabby, 60k★ · live ↗)

npx codeblast demo            # build a graph of the current repo, run one impact query, emit the map
npm i -g codeblast            # or install globally; needs Node ≥ 22.13 (built-in sqlite) or Bun

# Install as an agent skill (Claude Code, Codex, Cursor, and 14 more harnesses)
npx skills add alloevil/codeblast

Why not yet another LLM diagram tool

LLM diagrams:  code → model reads it → hand-drawn graph → render     graph = the model's opinion, unverifiable
codeblast:     code → deterministic tsc/AST parse → graph → project  graph = checkable facts

Every node, every edge, every claim carries file:line evidence you can open and verify. The LLM does exactly one job in the pipeline: giving modules human-readable names — node membership and edges always come from static analysis.

The three queries

# Build the graph: auto-detects TS monorepos / Python, hash-based incremental updates
# (full build of tRPC, 950 files, in ~20s)
codeblast index <repo> --db graph.db

# ① Impact — check the blast radius before you change anything
codeblast impact graph.db "createOrder" --json
#    → direct list = callsites you must review; tests list = tests you must run
#    → two channels: call-graph reachable (precision ~0.70, read first)
#      + import reachable (conservative supplement, don't skip)

# ② Change Map — structural diff between two refs
codeblast change <repo> main~5 main --json
#    → unexpected edges_added = a signal the change is out of scope

# ③ Architecture Map — interactive HTML: module → file → symbol drill-down,
#    symbols link to source lines
codeblast archmap graph.db --out arch.html --repo-url <github-url>

# Optional: mine git co-change coupling (protocol pairs, config + consumers —
# edges static analysis can't see)
codeblast cochange <repo> graph.db

PR bot (runs in CI, stays quiet by default)

Copy .github/workflows-template/codeblast.yml into your repo (it runs npx codeblast pr-comment, no other setup): every PR gets an automatic comment with structural changes + blast radius + new symbols with no test coverage; PRs with no structural change get zero comments. Replayed against 50 real commits: 42 correctly stayed silent, 87.5% of comments were useful.

The precision promise (bounded, and evidence-backed)

• TypeScript at function level: zero missed impact within statically analyzable scope. Verified by mutation testing: inject mutations into a real repo → run the full test suite to get the ground-truth impact set → compare against predictions. Current benchmark (tRPC, 950 files): 28/28 mutations, 100% recall, average precision 0.36 — favoring false positives over false negatives is a deliberate trade: in a controlled experiment, dropping the conservative edges raises precision to 0.70 but recall collapses to 14%. Data lives in eval/.
• Blind spots are explicitly flagged. A blind spot is any call or import that static analysis cannot resolve to an in-repo target — dynamic calls, unresolved calls, failed external-dependency resolution, subprocess boundaries, test-framework globals — not just dynamic calls; each is recorded in blind_spots with an "impact may be underestimated" warning, never silently dropped.
• Python is file-level. Dynamic typing makes function-level zero-miss guarantees impossible in principle, and we don't pretend otherwise.

For AI agents

before editing:  impact "symbol" --json    → callsite list into context, so nothing gets missed
after editing:   change HEAD~1 HEAD --json → self-check for scope creep and accidental deletions

The full contract and interpretation discipline (including "never pretend the blind-spot list is complete") is in SKILL.md. Agent conventions: AGENTS.md.

Status & roadmap

M0 graph engine → M1 Impact → M3 architecture map → M4 graph diff + PR bot → M5 precision extensions — all milestones accepted (each with a reproducible acceptance script). Single source of truth for design and acceptance criteria: intent.md.

MIT © 2026