Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
Understand Anything
Project Overview
An open-source tool combining LLM intelligence + static analysis to produce interactive dashboards for understanding codebases.
Prerequisites
- Node.js >= 22 (developed on v24)
- pnpm >= 10 (pinned via
packageManagerfield in rootpackage.json)
Architecture
- Monorepo with pnpm workspaces
- understand-anything-plugin/ — Claude Code plugin containing all source code:
- packages/core — Shared analysis engine (types, persistence, tree-sitter, search, schema, tours, plugins)
- packages/dashboard — React + TypeScript web dashboard (React Flow, Zustand, TailwindCSS v4)
- packages/mcp — Stdio MCP server (
bin/understand-anything-mcp.mjs) exposing graph status/search/explain/diff/onboard/dashboard tools to MCP clients (e.g. Devin via.devin/config.json) - src/ — Skill TypeScript source for
/understand-chat,/understand-diff,/understand-explain,/understand-onboard - skills/ — Skill definitions (
/understand,/understand-dashboard, etc.) - agents/ — Agent definitions (project-scanner, file-analyzer, architecture-analyzer, tour-builder, code-lesson-writer, graph-reviewer)
Dashboard
- Dark luxury theme: deep blacks (#0a0a0a), gold/amber accents (#d4a574), DM Serif Display typography
- Graph-first layout: 75% graph + 360px right sidebar
- No ChatPanel or Monaco Editor
- Sidebar tabs:
Info(ProjectOverview default → NodeInfo when node selected → LearnPanel in Learn persona, composing) andFiles(FileExplorer tree built from the structural graph) - Code viewer: prism-react-renderer source viewer that slides up from the bottom on file node click; an expand button promotes it into a full-screen modal. Source content is fetched from the dev server's
/file-content.jsonendpoint, gated by access token + a graph-derived path allowlist - Code lessons:
/understandPhase 5 dispatches thecode-lesson-writeragent to write.ua/code-lessons.json— per-file learning explanations aligned with the tour (detailed sections for tour-covered files, overview-only for the rest). The dev server andbin/viewer.mjsserve it from/code-lessons.json(same token gate); the code viewer renders it as a right-hand lesson panel where clicking a section highlights its line range. Optional file — absent means no panel. Line ranges may drift onPARTIAL_UPDATEuntil the next tour rerun - Schema validation on graph load with error banner
Agent Pipeline
- Agents write intermediate results to the data directory's
intermediate/subdirectory on disk (not returned to context) —.ua/intermediate/, or.understand-anything/intermediate/when that legacy directory is present - Agent model field is omitted from frontmatter so each platform falls back to its configured default —
inheritwas a Claude Code-only keyword that opencode (and similar tools) treated as a literal model id and rejected withProviderModelNotFoundError(see #167) /understandauto-triggers/understand-dashboardafter completion- Intermediate files cleaned up after graph assembly
Key Commands
pnpm install— Install all dependenciespnpm --filter @understand-anything/core build— Build the core packagepnpm --filter @understand-anything/core test— Run core testspnpm --filter @understand-anything/skill build— Build the plugin packagepnpm test— Run all tests (skill tests live at repo-roottests/skill/, picked up by rootvitest.config.ts)pnpm --filter @understand-anything/dashboard build— Build the dashboardpnpm dev:dashboard— Start dashboard dev serverpnpm lint— Run ESLint across the project
Conventions
- TypeScript strict mode everywhere
- Vitest for testing
- ESM modules (
"type": "module") - Knowledge graph JSON lives in the analyzed project's data directory:
.ua/for new projects, or the legacy.understand-anything/directory when it already exists (if.understand-anything/is present it is used for both reads and writes; otherwise.ua/). All bundled scripts and core code self-resolve this rule. - Core uses subpath exports (
./search,./types,./schema) to avoid pulling Node.js modules into browser
Gotchas
- tree-sitter: Uses
web-tree-sitter(WASM) instead of nativetree-sitter— native bindings fail on darwin/arm64 + Node 24 - Dashboard imports: Dashboard must only import from core's browser-safe subpath exports (
./search,./types,./schema), never the main entry point which pulls in Node.js modules
Scripts
scripts/generate-large-graph.mjs— Generates a fake knowledge graph for performance testing (e.g. large-graph layout). Writes to the project data directory'sknowledge-graph.json(.ua/knowledge-graph.json, or.understand-anything/when that legacy directory is present). Usage:node scripts/generate-large-graph.mjs [nodeCount](default: 3000 nodes). Not part of the production pipeline.
Devin Integration
- Generation: Devin loads
understand-anything-plugin/through its Claude-plugin compatibility. It reads.claude-plugin/plugin.jsonandhooks/hooks.json, setsCLAUDE_PLUGIN_ROOTfor hook commands, and loadsagents/asunderstand-anything:<name>subagents. There is deliberately no.devin-plugin/plugin.json, because a native manifest would take precedence over the Claude one. - Hooks: the PostToolUse matcher
^(Bash|exec)$covers Claude'sBashtool and Devin'sexectool. Both hook scripts emithookSpecificOutputJSON, which is the only form Devin injects into context, and they fall back to resolving paths from their own location. - Skills: Devin's agent shell has no plugin-root variable, so the plugin-root resolution blocks in
skills/understand*/SKILL.mdalso try$DEVIN_PLUGIN_ROOTand two levels above<SKILL_DIR>. Keep those candidates when you edit the blocks. - Consumption: the
packages/mcpMCP server (see its README) serves the status/search/explain/diff/onboard/dashboard tools. Don't duplicate those as skills.
Viewer Package
packages/viewer serves a committed graph without Claude Code, via npx <release-asset-url>. Update it when (a) the dashboard UI changes — the tarball embeds the built dist/ — or (b) the vite.config.ts dev-server middleware changes, which bin/viewer.mjs deliberately mirrors. On every release, repack (pack:release script) and re-upload the tarball to the GitHub release as understand-anything-viewer.tgz — exactly that name, the READMEs' releases/latest/download/ URL depends on it.
Versioning
When pushing to remote, bump the version in all seven of these files (keep them in sync):
understand-anything-plugin/package.json→"version"fieldunderstand-anything-plugin/.claude-plugin/plugin.json→"version"fieldunderstand-anything-plugin/packages/viewer/package.json→"version"fieldunderstand-anything-plugin/packages/mcp/package.json→"version"field.claude-plugin/plugin.json→"version"field.cursor-plugin/plugin.json→"version"field.copilot-plugin/plugin.json→"version"field
Note: .claude-plugin/marketplace.json does not carry a version — the plugins[] entry only supports name and source, and adding other fields causes marketplace schema validation failures.
Testing Local Plugin Changes
Claude Code caches installed plugins at ~/.claude/plugins/cache/understand-anything/understand-anything/<version>/. Symlinks don't work because Claude's Search/Glob tools can't follow them. To test local changes:
Build the packages:
pnpm --filter @understand-anything/core build pnpm --filter @understand-anything/skill buildFind the installed version (must match what the marketplace currently serves):
ls ~/.claude/plugins/cache/understand-anything/understand-anything/Copy your local plugin into the cache, replacing
<VERSION>with the version from step 2:rm -rf ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION> cp -R ./understand-anything-plugin ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>Start a fresh Claude Code session (existing sessions cache the old prompts in context).
Run
/understand --fullin the target project to verify.
Re-sync after further changes:
pnpm --filter @understand-anything/core build && \
cp -R ./understand-anything-plugin/* ~/.claude/plugins/cache/understand-anything/understand-anything/<VERSION>/
To revert to upstream: Uninstall and reinstall the plugin from the marketplace — it repopulates the cache from the upstream repo.