Understand-Anything/CLAUDE.md

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 packageManager field in root package.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)
  • 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, 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: ProjectOverview (default) → NodeInfo (node selected) → LearnPanel (Learn persona)
• Code viewer: styled summary overlay (slides up from bottom on file node click)
• Schema validation on graph load with error banner

Agent Pipeline

• Agents write intermediate results to .understand-anything/intermediate/ on disk (not returned to context)
• Agent models: sonnet for simple tasks (project-scanner, graph-reviewer), opus for complex (file-analyzer, architecture-analyzer, tour-builder)
• /understand auto-triggers /understand-dashboard after completion
• Intermediate files cleaned up after graph assembly

Key Commands

• pnpm install — Install all dependencies
• pnpm --filter @understand-anything/core build — Build the core package
• pnpm --filter @understand-anything/core test — Run core tests
• pnpm --filter @understand-anything/skill build — Build the plugin package
• pnpm --filter @understand-anything/skill test — Run plugin tests
• pnpm --filter @understand-anything/dashboard build — Build the dashboard
• pnpm dev:dashboard — Start dashboard dev server
• pnpm lint — Run ESLint across the project

Conventions

• TypeScript strict mode everywhere
• Vitest for testing
• ESM modules ("type": "module")
• Knowledge graph JSON lives in .understand-anything/ directory of analyzed projects
• 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 native tree-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

Versioning

When pushing to remote, bump the version in both of these files (keep them in sync):

• understand-anything-plugin/package.json → "version" field
• .claude-plugin/marketplace.json → plugins[0].version field