Understand Anything — Mental Model Wiki

Pages

1. The Mental Model: Graph-First Codebase UnderstandingThe single simplest model of the whole system: a CLI plugin triggers a sequential multi-agent pipeline that emits one JSON knowledge graph, which is then rendered as an interactive React Flow dashboard. Everything else — tree-sitter extractors, parsers, staleness checks, Zustand store — supports this central invariant. Understanding this flow lets you predict where any new feature, bug, or change lands.
2. Agent Pipeline: Five Phases from Scan to GraphThe /understand skill orchestrates five sequential agent phases: project-scanner (file discovery), file-analyzer (per-file nodes), architecture-analyzer (cross-cutting edges), tour-builder (guided walkthroughs), and assemble-reviewer (graph assembly and validation). Agents write intermediate JSON to .understand-anything/intermediate/ to avoid polluting context; results are merged and cleaned up. Auto-update mode replays stale phases after a git commit via the PostToolUse hook.
3. Schema & Type Contracts: Nodes, Edges, and AliasesThe knowledge graph is defined by two Zod schemas: NodeTypeSchema (21 canonical node types such as file, function, class, domain, article) and EdgeTypeSchema (35 edge types across 8 categories: structural, behavioral, data-flow, dependencies, semantic, infrastructure, domain, knowledge). Alias maps (NODE_TYPE_ALIASES, EDGE_TYPE_ALIASES) normalize LLM-generated variants to canonical forms at assembly time. This schema is the contract between the agent pipeline and the dashboard — both sides import from @understand-anything/core/types and @understand-anything/core/schema.
4. Static Analysis: Tree-Sitter Extractors & ParsersTwo plugin families produce deterministic graph nodes without LLM calls. Language extractors (TypeScript, Python, Go, Java, Rust, C++, Ruby, C#, PHP) use web-tree-sitter (WASM) via tree-sitter-plugin.ts to parse ASTs and emit function/class/module nodes. Config parsers (JSON, YAML, TOML, SQL, GraphQL, Dockerfile, Protobuf, Makefile, shell, Markdown, Terraform, .env) extract config/schema/document nodes. The plugin registry in registry.ts and discovery.ts wires both families together. The WASM constraint — no native bindings — is a hard invariant: never swap in the native tree-sitter package.
5. Staleness Detection & Incremental UpdatesThe knowledge graph is stored as .understand-anything/knowledge-graph.json alongside config.json (which records the last analyzed commit hash and user preferences such as language and autoUpdate). On each /understand invocation, staleness.ts compares git diff lastCommitHash..HEAD; if files changed, only affected nodes are removed and re-analyzed (incremental mode). --full forces a complete rebuild. The auto-update hook re-triggers analysis after every git commit when autoUpdate is true. Worktree redirect is a critical invariant: graphs generated inside a Claude Code worktree are redirected to the main repo root to prevent ephemeral loss.
6. Dashboard State Machine: Zustand Store & View ModesThe dashboard's single Zustand store (store.ts) owns all runtime state: the loaded KnowledgeGraph, active Persona (non-technical / junior / experienced), ViewMode (structural / domain / knowledge), FilterState (node types, complexities, layers, edge categories), selected node, search results via SearchEngine (Fuse.js fuzzy search on name/tags/summary/languageNotes), and the React Flow instance. The store is the single source of truth — components never hold local graph state. Key boundary: dashboard imports only from @understand-anything/core/search, /types, and /schema (browser-safe subpath exports); never the core main entry point, which pulls in Node.js modules.
7. Skill Surface: /understand, /understand-chat, /understand-diff & HooksEight skills are exposed: /understand (full graph build), /understand-dashboard (opens dashboard), /understand-chat (Q&A against the graph using context-builder.ts), /understand-diff (change analysis via diff-analyzer.ts), /understand-explain (node explanation via explain-builder.ts), /understand-onboard (onboarding guide via onboard-builder.ts), /understand-domain, and /understand-knowledge. The @understand-anything/skill package exports typed builders consumed by the chat/diff/explain/onboard skills. Hooks (hooks.json) fire PostToolUse on git commit to trigger auto-update and a PreToolUse hook to auto-update before /understand-chat responses. Agent models are all set to inherit for cross-platform compatibility.
8. Invariants, Failure Modes & Safe-Change RulesA synthesis of every load-bearing constraint in the system. Hard invariants: (1) use web-tree-sitter (WASM) only — native bindings break on darwin/arm64 + Node 24; (2) dashboard imports only browser-safe core subpath exports; (3) graphs inside git worktrees are redirected to the main repo root; (4) all five version fields must be bumped in sync when releasing. Key failure modes: stale graph after code changes (fix: run /understand or enable autoUpdate), broken incremental update when lastCommitHash is missing from config.json (fix: --full rebuild), dashboard blank on schema mismatch (fix: check WarningBanner, validate graph JSON against schema.ts). Safe-change rules: adding a new language extractor only requires a new file under extractors/ plus registry entry; adding a new edge type requires updating schema.ts alias maps and the EDGE_CATEGORY_MAP in store.ts; dashboard layout changes are isolated to components/ and never touch core.