understand-anything

Trigger phrases

Phrases that activate this skill when typed to Claude Code:

• /understand
• build a knowledge graph of this codebase
• map this repo
• explain this architecture
• onboard me on this project

What it does

understand-anything is a Claude Code plugin — a bundle that installs eight slash-commands, nine subagents, two hooks, and a set of bundled Node/Python scripts atomically via /plugin install understand-anything. It’s not a single skill; it’s a producer + reader pattern.

The producer is /understand. Run it against a directory and it:

1. Resolves the project root, handles git-worktree redirects, ensures @understand-anything/core is built via pnpm.
2. Dispatches the bundled project-scanner subagent to inventory files, detect languages and frameworks.
3. Batches files (20–30 per batch, ≤5 concurrent) and dispatches the bundled file-analyzer subagent to extract nodes (functions, classes, files, modules) and edges (calls, imports, contains, references) via a deterministic Tree-sitter pass followed by LLM semantic analysis.
4. Runs merge-batch-graphs.py to deduplicate and normalize across batches, then dispatches assemble-reviewer.
5. Dispatches architecture-analyzer with bundled language and framework context (./languages/*.md, ./frameworks/*.md).
6. Dispatches tour-builder to generate guided learning steps.
7. Writes the canonical artifact: $PROJECT_ROOT/.understand-anything/knowledge-graph.json (plus meta.json for fingerprints, config.json for preferences).

The seven sibling commands — /understand-chat, /understand-dashboard, /understand-diff, /understand-explain, /understand-onboard, /understand-domain, /understand-knowledge — are thin reader skills that consume that artifact. Their SKILL.md files don’t ship analysis scripts; they query the JSON that /understand produced. The shape collapses an “8-skill plugin” into one heavy producer and seven readers — incremental commits trigger re-analysis of only changed files via fingerprint comparison.

When to use it

Reach for it when:

• You’ve inherited an unfamiliar codebase and want a queryable map before opening files one by one.
• You’re onboarding a new contributor or agent and want them to ask architectural questions against a stable artifact instead of re-walking the tree on every prompt.
• You want a structural diff (/understand-diff) between two commits expressed in graph terms — nodes added/removed, edges rewired — not just line-level changes.
• The repo has stabilized enough that an LLM-built map is a useful index rather than a snapshot that goes stale by lunch.

When not to reach for it:

• Greenfield code where the architecture is changing hourly — the graph regenerates fine, but the cognitive payoff is low.
• Very small codebases where reading the directory is faster than running the pipeline.
• Repos where the LLM-analysis cost of a full pass exceeds the value of the graph. The pipeline runs file-analyzer concurrently across batches, so token spend on first run scales with file count.

Install

The canonical install path is the plugin marketplace, not a bare skill copy:

/plugin marketplace add Lum1104/Understand-Anything
/plugin install understand-anything

A universal installer is also available for non-Claude-Code platforms (Cursor, Codex, Copilot, Gemini CLI):

curl -fsSL https://raw.githubusercontent.com/Lum1104/Understand-Anything/main/install.sh | bash

The plugin requires Node ≥22 and pnpm ≥10 (the install script bootstraps both if missing). LLM credentials are inherited from whichever host you’re running inside — Claude Code, Cursor, Codex, etc. There’s no separate API key.

What a session looks like

Phase 0–7 of /understand runs end-to-end on first invocation; subsequent runs use the stored git commit hash to re-analyze only changed files. The output is one file:

$PROJECT_ROOT/.understand-anything/knowledge-graph.json

That artifact conforms to a fixed schema — 13 node types, 26 edge types, layers, tour steps. Once it exists, the seven sibling commands light up:

• /understand-chat — natural-language Q&A against the graph.
• /understand-dashboard — launches a local UI to browse nodes and edges visually.
• /understand-diff — graph-level diff between two commits.
• /understand-explain <file_or_function> — drill into a single node with its incoming/outgoing edges in context.
• /understand-onboard — generates a guided learning tour for a new contributor.
• /understand-domain — extract a domain sub-graph (only nodes matching a topic).
• /understand-knowledge — query the graph as a knowledge base.

The discipline the design enforces: analysis runs once, queries run cheap. Compare to ad-hoc /repo-overview skills that re-read the tree every prompt — the per-query LLM cost there is unbounded; here it’s bounded by the size of the JSON.

Different angle from codebase-onboarding-engineer (a Sitarzewski persona that walks a human through a repo verbally without building an artifact) and improve-codebase-architecture (a Pocock skill that proposes refactors against an existing CONTEXT.md). understand-anything builds the substrate the other two can read against.

Receipts

TODO — to be filled in from a real session. When /understand is run in production use, capture: total token spend on the first-pass file-analyzer batches, wall-clock time for a repo of N files, fidelity of the resulting graph against the actual import structure (spot-check 5–10 nodes), whether --review LLM validation finds dangling refs the deterministic pass missed, and whether /understand-diff against two real commits surfaces structural changes a line-level diff buried. Also worth capturing: does the dashboard UI add legible value over reading the JSON directly, or is the JSON the load-bearing artifact?

Caveat to surface alongside the firsthand notes: the upstream repo went from 0 → 23,193 stars in 8 weeks (created 2026-03-15). The version cadence is fast (v2.0.0 → v2.7.4 in the same window). The skill content is substantive — Tree-sitter + LLM hybrid is a real design choice, the dispatch graph is concrete — but the star metric should be read with the same caution as any rapid-growth repo.

Source and attribution

Originally written by Lum1104. The plugin’s canonical layout lives at understand-anything-plugin/ — with skills under skills/<slug>/, subagents under agents/<slug>.md, hooks under hooks/, and the plugin manifest at .claude-plugin/plugin.json.

The producer-plus-readers pattern (/understand builds the artifact, seven siblings query it) and the bundled-subagent dispatch model are documented in this site’s companion post A Claude Code plugin’s manifest is 12 lines — the rest is convention, which walks through the marketplace and plugin manifests verbatim.

License: MIT. You can install, adapt, and redistribute the plugin, with attribution preserved.

This page documents the plugin from a practitioner’s perspective. For the formal spec, the homepage, and any updates, defer to the source repo and understand-anything.com.