Analysis — Understand-Anything

ANALYSIS: Understand-Anything

Summary

Understand-Anything is a TypeScript/Node.js Claude Code skill (slash commands /understand and /understand-domain) that orchestrates a multi-agent pipeline to produce an interactive in-IDE knowledge graph dashboard from a codebase. Its core differentiator is a dual-graph view: a structural graph (files, functions, classes) and a domain graph (business flows, processes, steps) generated by a domain-analyzer agent. The tool targets developer comprehension and onboarding rather than agent token reduction — no token metrics are claimed. With 8,081 GitHub stars and MIT license it has significant community traction. Source review confirms the persistence model, pipeline structure, hybrid static+LLM analysis strategy, supported language breadth, and graph schema in detail.

What it does (from reference documentation)

Multi-agent pipeline

Seven agents invoked via slash commands (verified against agent definition files):

Agent	Role
`project-scanner`	Discover files, detect languages and frameworks
`file-analyzer`	Extract functions, classes, imports; produce graph nodes and edges
`architecture-analyzer`	Identify architectural layers
`tour-builder`	Generate guided learning tours ordered by dependency
`assemble-reviewer`	Review merge-script output for semantic issues the script cannot catch
`graph-reviewer`	Validate graph completeness and referential integrity (opt-in via `--review`)
`domain-analyzer`	Extract business domains, flows, and process steps (via `/understand-domain`)
`article-analyzer`	Extract entities, claims, implicit relationships from wiki articles (via `/understand-knowledge`)

The triage listed 6 agents. Source confirms there are actually 8 agent definition files. The assemble-reviewer is a distinct agent (not the same as graph-reviewer) that runs inline after every batch merge. The article-analyzer supports the third slash command /understand-knowledge that was not documented in the original triage.

File analyzers run in parallel (up to 5 concurrent, 20–30 files/batch) (verified). The graph-reviewer runs inline by default; --review flag triggers full LLM-backed validation (verified).

Interface

Slash commands: /understand (structural + architectural analysis), /understand-domain (business domain extraction), /understand-knowledge (Karpathy-pattern wiki knowledge base analysis) — the third command was not in the triage
Secondary commands: /understand-chat, /understand-diff, /understand-explain, /understand-onboard, /understand-dashboard — all have separate skill definitions
Multi-platform installation: Claude Code, Codex, Cursor, VS Code + Copilot, Gemini CLI, OpenCode, Antigravity, Pi Agent, OpenClaw (10 platforms, verified against README compatibility table)
Output: interactive in-IDE dashboard (React + React Flow + Zustand + TailwindCSS v4) with structural graph, domain graph, fuzzy+semantic search, diff impact analysis, and guided tours

Incremental updates

Only changed files since the last run are re-analyzed (verified via staleness.ts — uses git diff <lastCommitHash>..HEAD --name-only). Per-file content fingerprinting (fingerprints.json) tracks structural changes at function/class granularity. No latency or throughput benchmarks are provided.

Source review

Monorepo structure (verified)

The plugin is organized as a pnpm monorepo with two packages:

understand-anything-plugin/packages/core — shared analysis engine (@understand-anything/core): types, persistence, tree-sitter parsing, fuzzy/semantic search, schema validation, tour/layer generation, change classification, fingerprinting
understand-anything-plugin/packages/dashboard — React + TypeScript web dashboard
understand-anything-plugin/src/ — TypeScript skill implementations for secondary commands (/understand-chat, /understand-diff, /understand-explain, /understand-onboard)
understand-anything-plugin/skills/ — Skill definition markdown files (one directory per slash command)
understand-anything-plugin/agents/ — Agent definition markdown files (8 files)

Agent pipeline in detail (verified)

The /understand SKILL.md defines a 7-phase pipeline:

Phase	Name	What happens
0	Pre-flight	Git hash check; subdomain graph merge; incremental vs. full decision
0.5	Ignore config	Generate/verify `.understandignore` (user confirms before proceeding)
1	SCAN	`project-scanner` agent discovers files, detects languages, resolves imports
2	ANALYZE	`file-analyzer` subagents (up to 5 concurrent, 20–30 files/batch); results written to `.understand-anything/intermediate/batch-N.json`
3	ASSEMBLE REVIEW	`assemble-reviewer` agent reviews merge output; merge-batch-graphs.py Python script combines batches
4	ARCHITECTURE	`architecture-analyzer` agent identifies 3–10 architectural layers
5	TOUR	`tour-builder` agent creates 5–15 guided learning steps
6	REVIEW	Inline deterministic validation script OR full `graph-reviewer` (if `--review`); writes `knowledge-graph.json` then auto-launches `/understand-dashboard`

All intermediate files are written to disk at .understand-anything/intermediate/ (verified via persistence module and SKILL.md). They are cleaned up after graph assembly. This means agents write to disk rather than returning to context — a design decision that limits context growth for large codebases.

Knowledge graph schema (verified)

Defined in packages/core/src/types.ts and schema.ts:

21 node types: 5 code (file, function, class, module, concept), 8 non-code (config, document, service, table, endpoint, pipeline, schema, resource), 3 domain (domain, flow, step), 5 knowledge (article, entity, topic, claim, source)
35 edge types across 8 categories: Structural, Behavioral, Data flow, Dependencies, Semantic, Infrastructure, Domain, Knowledge
KnowledgeGraph root object: { version, kind?, project: ProjectMeta, nodes: GraphNode[], edges: GraphEdge[], layers: Layer[], tour: TourStep[] }
Persistence: knowledge-graph.json (structural) and domain-graph.json (domain) both live in .understand-anything/ in the analyzed project directory — they survive IDE restarts (verified via persistence/index.ts)

The triage claim that “dashboard persistence format is undocumented” is contradicted by source: the graph is persisted as JSON on disk and loaded on dashboard open. The format is fully typed and schema-validated via Zod.

File analysis: hybrid static + LLM (verified)

The file-analyzer agent uses a two-phase approach:

Phase 1 — deterministic structural extraction: the agent writes and executes a Node.js (or Python fallback) script that extracts functions, classes, imports, exports, and metrics via regex/AST pattern matching. For non-code files (YAML, SQL, Dockerfile, Terraform, etc.), specialized parsers run deterministically.
Phase 2 — LLM semantic analysis: the agent uses LLM inference to produce summaries, tags, complexity ratings, and semantic edges based on the Phase 1 script output.

Additionally, packages/core includes a tree-sitter-plugin.ts using web-tree-sitter (WASM) for TypeScript/JavaScript — a real AST parser. The triage claim that the tool “relies on LLM-based file analysis rather than deterministic AST parsing” is partially wrong: static analysis and AST parsing handle structure; LLM inference handles semantics.

Non-code file support (verified)

The tool has deterministic parsers for 13 non-code file types: Dockerfile, docker-compose YAML, .env, GraphQL, JSON, Makefile, Markdown, Protobuf, Shell, SQL, Terraform, TOML, YAML. The project-scanner assigns a fileCategory (code, config, docs, infra, data, script, markup) to every file. The architecture-analyzer, tour-builder, and all agents treat non-code files as first-class nodes.

Language coverage (verified)

39 built-in language configurations in packages/core/src/languages/configs/. Includes: TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, C++, C#, Ruby, PHP, Swift, CSS, HTML, SQL, GraphQL, Protobuf, Terraform, YAML, JSON, Markdown, Dockerfile, Shell, and more. The triage claim of “unsupported language list” is resolved: coverage is broad but relies on regex/AST for code structure and LLM for semantics.

Fuzzy and semantic search (verified)

Two search implementations in packages/core/src/:

search.ts: fuzzy search via Fuse.js (weighted across name, tags, summary, languageNotes)
embedding-search.ts: cosine similarity search using pre-computed embeddings (vector search for semantic queries)

LLM API calls during indexing (verified)

All agent definition files set model: inherit — they inherit the model from the calling platform (Claude Code, Cursor, etc.). Each file-analyzer subagent performs LLM inference for summaries, tags, and semantic edge generation per batch. Architecture-analyzer, tour-builder, domain-analyzer, graph-reviewer, and assemble-reviewer also make LLM calls. The triage flag “LLM API calls during indexing are likely but undisclosed” is confirmed as accurate; the README still does not quantify per-run cost.

`/understand-knowledge` — third slash command (not in triage)

A third major capability absent from the triage: /understand-knowledge analyzes Karpathy-pattern LLM wiki knowledge bases (markdown files with [[wikilink]] syntax + index.md + optional raw/ sources). A deterministic Python parse script extracts wikilinks and categories; article-analyzer subagents then extract implicit entities, claims, and cross-article relationships. The output uses the same KnowledgeGraph schema with kind: "knowledge" and knowledge-specific node types (article, entity, topic, claim, source).

Dashboard (verified)

React + React Flow + Zustand + TailwindCSS v4. Dark luxury theme (#0a0a0a background, gold/amber accents). Graph-first layout: 75% graph + 360px right sidebar. No chat panel or code editor embedded. Sidebar transitions: ProjectOverview (default) → NodeInfo (node selected) → LearnPanel (Learn persona). The persona-adaptive UI is confirmed: a “Learn” persona mode exists as a sidebar panel. The claim that “12 programming patterns explained in context” (language lessons) is confirmed via language-lesson.ts in the core package.

Benchmark claims — verified vs as-reported

No quantitative claims are made. The reference documentation explicitly notes: “No token reduction figures claimed; value proposition is developer onboarding and codebase comprehension.”

The README states incremental update capability (re-analyzes changed files only) — (verified): staleness.ts implements getChangedFiles() using git diff <hash>..HEAD --name-only; the SKILL.md uses this to select only changed files for re-analysis. No latency figures are provided.

There is no benchmark harness to reproduce. The only performance-related script is scripts/generate-large-graph.mjs, which generates a synthetic 3,000-node graph for dashboard rendering tests — this is explicitly “not part of the production pipeline” (CLAUDE.md).

Verdict: No metrics to verify. The tool’s value proposition is qualitative and cannot be assessed via token benchmarks. The incremental update mechanism is implemented and verified.

Architectural assessment

What’s genuinely novel

Domain graph view. (verified) The domain-analyzer agent extracts a business domain ontology — domains, flows, steps — and maps code to them via a three-level hierarchy (Domain → Flow → Step). The domain-graph.json is a separate persisted file from knowledge-graph.json. No other tool in this survey offers a code-to-business-process graph.
Knowledge base graph (/understand-knowledge). Not in the triage. The article-analyzer agent applies knowledge graph extraction to Karpathy-pattern LLM wikis — extracting implicit entities, claims, and cross-article relationships beyond explicit wikilinks. This is a third use case distinct from codebase and domain analysis.
Hybrid static + LLM analysis. The two-phase file-analyzer (deterministic script first, LLM semantic layer second) is a principled design: structure is never delegated to LLM; only summaries, tags, and semantic edge inference are. The assemble-reviewer catches LLM hallucination at assembly time. This is more robust than pure LLM extraction.
Dependency-ordered guided tours. (verified) The tour-builder agent runs a graph topology script (fan-in/fan-out ranking, entry-point detection, dependency chains) before designing tour steps — structurally grounded, not purely LLM-generated.
Persona-adaptive UI. (partially verified) Confirmed as a “Learn” persona sidebar panel in the dashboard source. Full persona differentiation (junior dev, PM, power user) is described in README but the dashboard implementation shows a single “Learn” mode — the per-persona detail calibration may be less granular than the README implies.
Multi-platform deployment via model: inherit. (verified) All agents use model: inherit for the LLM call, which means the skill runs identically on Claude Code, Cursor, Gemini CLI, and other platforms without modification.

Gaps and risks

LLM API calls during indexing are confirmed but unquantified. Every file batch, architecture pass, tour, and domain extraction involves LLM inference. Per-run cost scales with codebase size and is not disclosed.
graph-reviewer is opt-in for full validation. (verified) Default inline validation is a deterministic Node.js script (checks for missing IDs, dangling edges, duplicate nodes, layer coverage). The full LLM graph-reviewer runs only with --review. The inline script is well-specified in the SKILL.md but cannot catch semantic errors.
>100 files gate. (verified) The SKILL.md gates the analysis at >100 files and asks for user confirmation — implicit acknowledgment that large codebases may be slow or expensive.
Domain graph quality is LLM-dependent. Business domain extraction from code is a hard inference problem. The domain-analyzer agent has well-defined output constraints (2–6 domains, 2–5 flows per domain, 3–8 steps per flow) but no accuracy benchmark exists.
No benchmark against comprehension outcomes. The tool’s goal is developer understanding, but there is no study or metric measuring whether tours, domain graphs, or persona-adaptive UI actually reduce onboarding time or error rates.

Recommendation

Evaluate for onboarding and domain mapping use cases. If the primary need is helping a developer (or agent) understand what a codebase does in business terms — not just how it is structured — the domain-analyzer / /understand-domain path offers capability unavailable elsewhere in this survey.

Consider /understand-knowledge for LLM wiki graphs. If the team maintains a Karpathy-pattern knowledge base, this is the only tool surveyed that can generate an entity/claim/relationship graph from it.

Do not use as a substitute for structural graph queries. For call-path tracing, impact analysis, and token-efficient structural lookup, codebase-memory-mcp’s deterministic AST graph is more reliable and has lower per-query cost.

Clarify LLM API cost before adopting. The confirmed per-run API cost for large codebases is the most important operational unknown. Run /understand on a mid-sized project with API usage logging before committing to this tool in cost-sensitive agent workflows. The >100 file gate is the practical trip wire.

Treat domain graph output as a starting point. Business process extraction from code is inherently heuristic. Use the domain graph to orient, then verify key process claims against actual source.

Comparison hooks (for ANALYSIS.md matrix)

Dimension	Understand-Anything
Approach	Multi-agent LLM pipeline → interactive structural + domain + knowledge graph dashboard
Compression (vs grep)	Not applicable — no token reduction claim or metric
Token budget model	None — focus is developer comprehension, not agent token efficiency
Injection strategy	In-IDE dashboard; MCP tool for agent access
Eviction	N/A — no context injection pipeline
Benchmark harness	None (generate-large-graph.mjs is a rendering test fixture, not a pipeline benchmark)
License	MIT
Maturity	8,081 stars; last commit 2026-04-10; TypeScript/Node.js; version 2.3.1