SUPERGRAPH

The map your agent needs

01 — The Output

supergraph.txt

Domains, schemas, modules, types, and edges — unified into one file. An agent reads it once and knows the entire architecture. A human greps it and gets answers.

audit/supergraph.txt — real output, 21 packages

SUPERGRAPH | 2026-03-05

# PART 1 — DOMAINS

[guild]
r/guild GET /v2/guilds/:id  cache:60s
c/guild createGuild,updateGuild,deleteGuild
z/GuildSchema id:str name:str urlName:str? imageUrl:str? +8
t/guilds id:int name:varchar url_name:varchar +12

# PART 2 — PACKAGES

[fortress]
actors/orchestrator [68/93]<-2 OrchestratorActorContext,actor,+63
events [119/120]<-16 AbortEvent,ActorErrorLog,+111

# PART 3 — TYPES

GuildResponse { id:num name:str urlName:str roles:Role[] +6 }
CreateGuildInput { name:str urlName:str? description:str? }

domains

Domain-Aware

Routes, controllers, Zod schemas, SQL tables, and Redis keys grouped by domain.

schemas

Full Schema Fields

Zod schemas, SQL tables, and TS types with field definitions inline. No separate lookup needed.

layers

Three Detail Levels

supergraph.txt (architecture), symbols.txt (tiered signatures), symbols-full.txt (complete source bodies). Plus supergraph-compact.txt for tight context windows.

02 — Deep Audit

/deep-audit pkg/src

Claude Code slash command. Point it at a package, it reads the supergraph map, audits source files across 10 phases, writes findings and fix plans to disk. Say "do all" and it executes them.

Generate & Read

Runs supergraph, reads all artifacts. Full context before analysis begins.

Structural Audit

Dead exports, circular deps, complexity hotspots, oversized modules.

Deep Read

Source files prioritized by risk. Duplicates, inconsistencies, bugs, unfinished features.

Cross-Cutting

Architectural coherence, abstraction consistency, SRP violations.

Data Flow

Schema-type mismatches, unsafe assertions, error paths, missing validation.

Logic

Decision table gaps, guard consistency, temporal ordering bugs.

Invariants

Property-based tests on pure functions. Distinguishes real bugs from wrong invariants.

Plans & Execute

Groups findings into actionable plans by severity. Dispatches fixes via parallel subagents.

Output: audit/<pkg>/findings.md + audit/<pkg>/plans/. No subagent delegation during analysis — full cross-file context throughout.

02b — Deep Read

/deep-read topic

Loads symbols-full.txt — every function body, every type definition, every signature in the entire codebase. Then answers implementation questions with full source context.

/high-level

Architecture (~8KB)

Loads supergraph-compact.txt. Module names, import counts, domain grouping. Fast. "How is this organized?"

/deep-read

Source-Level (~10MB)

Loads symbols-full.txt. Every function body, every signature. Complete. "How does X work? Is there a bug in Y?"

Parse once. Query everything.

03 — Interactive Intelligence

Query your graph

Parse once, query many times. Impact analysis, change detection, and 360-degree symbol context — all instant via persistent graph cache.

supergraph impact — blast radius analysis

$ supergraph impact createGuild

# Impact Analysis: createGuild
# Risk: CRITICAL — 23 dependents across 4 packages

Depth 0 (direct)
  [fortress]  orchestrator ← calls createGuild
  [fortress]  guild-handler ← imports createGuild
  [api]       guild-router ← imports createGuild

Depth 1 (transitive)
  [fortress]  actor-system ← imports orchestrator
  [api]       v2-routes ← imports guild-router
  [dashboard] guild-form ← imports guild-handler
  ...+17 more

supergraph context — 360° symbol view

$ supergraph context GuildSchema

# Symbol Context: GuildSchema
# Package: @app/schemas — Type: zod-schema

Incoming (who uses this)
  guild-router     validates with GuildSchema
  guild-handler    validates with GuildSchema
  guild-form       imports GuildSchema
  guild.test       imports GuildSchema

Outgoing (what this uses)
  RoleSchema       extends
  ImageUrlSchema   references

supergraph detect-changes — pre-commit scope

$ supergraph detect-changes

# Changed symbols (from git diff)
createGuild  [guild]   MODIFIED  risk:CRITICAL
GuildSchema  [schemas] MODIFIED  risk:HIGH
guildUtils   [utils]   MODIFIED  risk:LOW

# Suggested re-analysis
supergraph impact createGuild  — 23 dependents
supergraph impact GuildSchema  — 11 dependents

impact

Blast Radius

BFS through the dependency graph. See every module that breaks when you change a symbol, grouped by depth with risk scoring.

context

Symbol Context

Every caller, importer, and extender of any symbol. Incoming and outgoing references grouped by relationship type.

detect

Change Detection

Maps your git diff to affected symbols and their dependents. Shows risk levels and suggests which analyses to re-run before commit.

Graph Cache: Supergraph serializes the parsed graph to disk. Parse once, then run impact, context, and detect-changes instantly without re-analyzing source files.

04 — MCP Server

supergraph serve

Model Context Protocol server that exposes supergraph intelligence as tools for AI agents. Your agent queries the graph directly — no copy-pasting, no context window waste.

.mcp.json — configuration

{
  "mcpServers": {
    "supergraph": {
      "command": "supergraph",
      "args": ["serve"]
    }
  }
}

supergraph_context

Symbol Context

Agent asks "who uses this function?" and gets the full incoming/outgoing reference graph for any symbol.

supergraph_impact

Impact Analysis

Agent asks "what breaks if I change this?" and gets the blast radius with risk scoring before making edits.

supergraph_detect_changes

Change Detection

Agent checks which symbols are affected by the current diff and what needs re-testing.

supergraph_query

Graph Query

Agent runs arbitrary queries against the dependency graph — find paths, filter by package, search symbols.

supergraph_map

Full Map

Agent loads the complete supergraph into its context window. The architecture map, on demand.

Works with: Claude Code, Cursor, Windsurf, and any AI tool that supports the Model Context Protocol. Run supergraph serve and your agent gains full codebase intelligence.

05 — Visualization

supergraph.html

Self-contained interactive module graph. Zero dependencies. The background of this page is a live one.

Key	Action
`p`	Toggle physics
`l`	Toggle labels
`scroll`	Zoom
`drag`	Pan / pin nodes
`click`	Inspect node symbols