CLAUDE.md

1# Understand Anything
2 
3## Project Overview
4An open-source tool combining LLM intelligence + static analysis to produce interactive dashboards for understanding codebases.
5 
6## Prerequisites
7- Node.js >= 22 (developed on v24)
8- pnpm >= 10 (pinned via `packageManager` field in root `package.json`)
9 
10## Architecture
11- **Monorepo** with pnpm workspaces
12- **understand-anything-plugin/** — Claude Code plugin containing all source code:
13  - **packages/core** — Shared analysis engine (types, persistence, tree-sitter, search, schema, tours, plugins)
14  - **packages/dashboard** — React + TypeScript web dashboard (React Flow, Zustand, TailwindCSS v4)
15  - **src/** — Skill TypeScript source for `/understand-chat`, `/understand-diff`, `/understand-explain`, `/understand-onboard`
16  - **skills/** — Skill definitions (`/understand`, `/understand-dashboard`, etc.)
17  - **agents/** — Agent definitions (project-scanner, file-analyzer, architecture-analyzer, tour-builder, graph-reviewer)
18 
19## Dashboard
20- Dark luxury theme: deep blacks (#0a0a0a), gold/amber accents (#d4a574), DM Serif Display typography
21- Graph-first layout: 75% graph + 360px right sidebar
22- No ChatPanel or Monaco Editor
23- Sidebar tabs: `Info` (ProjectOverview default → NodeInfo when node selected → LearnPanel in Learn persona, composing) and `Files` (FileExplorer tree built from the structural graph)
24- 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.json` endpoint, gated by access token + a graph-derived path allowlist
25- Schema validation on graph load with error banner
26 
27## Agent Pipeline
28- 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
29- Agent model field is omitted from frontmatter so each platform falls back to its configured default — `inherit` was a Claude Code-only keyword that opencode (and similar tools) treated as a literal model id and rejected with `ProviderModelNotFoundError` (see #167)
30- `/understand` auto-triggers `/understand-dashboard` after completion
31- Intermediate files cleaned up after graph assembly
32 
33## Key Commands
34- `pnpm install` — Install all dependencies
35- `pnpm --filter @understand-anything/core build` — Build the core package
36- `pnpm --filter @understand-anything/core test` — Run core tests
37- `pnpm --filter @understand-anything/skill build` — Build the plugin package
38- `pnpm test` — Run all tests (skill tests live at repo-root `tests/skill/`, picked up by root `vitest.config.ts`)
39- `pnpm --filter @understand-anything/dashboard build` — Build the dashboard
40- `pnpm dev:dashboard` — Start dashboard dev server
41- `pnpm lint` — Run ESLint across the project
42 
43## Conventions
44- TypeScript strict mode everywhere
45- Vitest for testing
46- ESM modules (`"type": "module"`)
47- 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.
48- Core uses subpath exports (`./search`, `./types`, `./schema`) to avoid pulling Node.js modules into browser
49 
50## Gotchas
51- **tree-sitter**: Uses `web-tree-sitter` (WASM) instead of native `tree-sitter` — native bindings fail on darwin/arm64 + Node 24
52- **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
53 
54## Scripts
55- `scripts/generate-large-graph.mjs` — Generates a fake knowledge graph for performance testing (e.g. large-graph layout). Writes to the project data directory's `knowledge-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.
56 
57## Viewer Package
58`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.
59 
60## Versioning
61When pushing to remote, bump the version in **all six** of these files (keep them in sync):
62- `understand-anything-plugin/package.json` → `"version"` field
63- `understand-anything-plugin/.claude-plugin/plugin.json` → `"version"` field
64- `understand-anything-plugin/packages/viewer/package.json` → `"version"` field
65- `.claude-plugin/plugin.json` → `"version"` field
66- `.cursor-plugin/plugin.json` → `"version"` field
67- `.copilot-plugin/plugin.json` → `"version"` field
68 
69Note: `.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.
70 
71## Testing Local Plugin Changes
72 
73Claude 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:
74 
751. **Build the packages:**
76```bash
77   pnpm --filter @understand-anything/core build
78   pnpm --filter @understand-anything/skill build
79```
80 
812. **Find the installed version** (must match what the marketplace currently serves):
82```bash
83   ls ~/.claude/plugins/cache/understand-anything/understand-anything/
84```
85 
863. **Copy your local plugin into the cache**, replacing `<VERSION>` with the version from step 2:
87```bash
88   rm -rf ~/.claude/plugins/cache/understand-anything/understand-anything/&lt;VERSION&gt;
89   cp -R ./understand-anything-plugin ~/.claude/plugins/cache/understand-anything/understand-anything/&lt;VERSION&gt;
90```
91 
924. **Start a fresh Claude Code session** (existing sessions cache the old prompts in context).
93 
945. **Run `/understand --full`** in the target project to verify.
95 
96**Re-sync after further changes:**
97```bash
98pnpm --filter @understand-anything/core build && \
99cp -R ./understand-anything-plugin/* ~/.claude/plugins/cache/understand-anything/understand-anything/&lt;VERSION&gt;/
100```
101 
102**To revert to upstream:** Uninstall and reinstall the plugin from the marketplace — it repopulates the cache from the upstream repo.
103