Highlights
New analysis mode: /understand-figma (#559) — by @gruming
Point the tool at a Figma file and get the same navigable knowledge graph you get for code: pages → screens → components/variants/instances, plus a light design-system model (design tokens and uses_token edges). Deterministic parsing via the Figma REST API, LLM enrichment via a new design-analyzer agent, screen thumbnails in the dashboard sidebar, incremental UP_TO_DATE re-runs, and FIGMA_TOKEN kept strictly in the request header. Schema additions are backward compatible (6 node types, 3 edge types, kind:"design"). Follow-up fixes landed for real-API style-key bridging, published component keys, kind-scoped alias normalization, and dashboard edge-category filters.
Data directory renamed to .ua/ — fully backward compatible
Analysis artifacts now live in .ua/ instead of .understand-anything/. Projects analyzed by older versions need no migration: when a legacy .understand-anything/ directory exists it keeps being used for both reads and writes. The resolution rule is implemented once in core (resolveUaDir) and honored by every bundled script, skill, agent definition, hook, and the dashboard dev server.
New language support
New platform support
Merge-pipeline reliability
- Structural subdomain edges (
contains_flow/flow_step/cross_domain) are no longer silently dropped: loud warnings, a persisted merge-report.json, and automatic retry on the next run (#529).
- Batch files that load but contribute zero nodes/edges are flagged in the phase report instead of vanishing into a partial merge (#484).
- Karpathy wiki parser handles title-case
Index.md/Log.md and article-root-prefixed [[wiki/...]] links (#342).
- Cross-layer container layout cache fix (#541) — by @computersniper; UTF-8 domain context on Windows (#524) — by @multimail-dev; Phase 7 cleanup and scan-result preservation fixes (#387, #332) — by @tirth8205 and @ZebangCheng.
Security hardening
Pipeline performance & DX
- Semantic batching and output chunking (#204),
/understand pipeline perf (#346) — by @tirth8205
- Conversation-language auto-detection on first run (#378) — by @BozhengLong
- Config schema validation tests (#471) — by @yiziff; CI on Node 24 runtimes.
Full Changelog: v2.7.3...v2.9.0
详细ChangeLog
Highlights
Localized analysis output — --language (#142, #145) — by @zhushen12580
/understand (and friends) now accept a --language flag. Architecture summaries, node descriptions, tours, and onboarding content are generated in the language you ask for, end-to-end through the agent pipeline. Documented across every README.
Dashboard i18n (#142 stack + 9d1318a)
The dashboard UI ships translation files alongside the analysis pipeline:
- All UI strings (sidebar, code viewer, search, tours, mobile layout) routed through
I18nProvider.
- New: Russian (
ru) joins the existing locales. MobileLayout is now wrapped in the provider so mobile screens localize too.
- Output language read from the same
outputLanguage config key for consistency between generated content and chrome.
Unified install script (#123)
Replaced the per-platform installer pile with a single install.sh / install.ps1 that detects the target CLI (Claude Code, Codex, Cursor, Copilot CLI, opencode, Gemini CLI, KIMI, Cline, Hermes, Mistral vibe) and wires up the right symlinks and config. Uninstall is robust against partial state; reparse deletes are guarded.
New platform support
- KIMI CLI (#134) — install + skill plumbing.
- Cline (#116) — install + skill plumbing.
- Hermes (#91) — open-source agent compatibility, README refresh.
- Mistral vibe (#127, by @3ng7n33r) — install script entry.
Test-coverage visualization — tested_by edges + dashboard badge (#122 / issue #113)
A deterministic tested_by linker runs during merge, with a swap-then-supplement strategy that recovers edges the per-file batches drop and a max-weight Pass-1 dedup. Tested files now render a small badge on their node card so you can spot uncovered code at a glance.
Dashboard file/class dual-view toggle (#132) — by @Xingkai98
Toggle between file-level and class-level structural views to cut clutter on large object-oriented codebases. View-state resets are scoped so the toggle stays sane when switching layers, and the detail toolbar hides in domain view where it doesn't apply.
Theme settings expose a heading-font override so teams can match their internal design system without forking.
Mobile layout + responsive dashboard (880e223)
The dashboard now has a real mobile layout instead of a horizontally-scrolling desktop. Sidebar collapses, the code viewer adapts to portrait, and tour navigation works on touch.
Closed 12 sources of silent data loss in graph extraction (c49c46d)
A pipeline-wide audit identified twelve places where nodes or edges were being quietly dropped during batched file analysis and merging. All twelve are now closed and covered:
imports edges recovered when file-analyzer batches drop them (05fd423).tested_by malformed tags coerced before adding (fdfa331, issue #113).- File-analyzer preserves language and falls back when imports unresolved (
7834f9b).
- Canonical edge direction persisted during merge so dedup doesn't lose half the edges (
f71bad5, in 2.7.1).
- Fingerprints merge made unambiguous in Phase 3d so re-runs converge (
dd8b724, in 2.7.2).
.understandignore exclusions actually applied in Phase 0 of auto-update (5304ff0).build-fingerprints.mjs bundled and Phase 7 reordered so incremental updates work on fresh installs (e7af9ae, in 2.7.3).
Auto-update / incremental pipeline (2.7.x line)
Structural fingerprinting (--auto-update / --no-auto-update) became real in the 2.7 line: only changed files re-run through analysis, fingerprints merge deterministically, and Phase 0 honors .understandignore. Big speedup on repeat runs against large repos.
Dashboard ACCESS_TOKEN override (1779cbd)
The dev server's access token can be overridden via env var for embedded/CI use cases without editing config.
Other contributions since v2.5.0
Huge thanks to everyone who improved the project this cycle:
- #147 — @rustanacexd: resolve
/understand-domain plugin root at runtime so symlink installs find their agent prompts.
- #139 — @nieao: Windows path handling and zod schema null compatibility in
/understand-knowledge.
- #127 — @3ng7n33r: add Mistral vibe CLI to the install script.
- #124 — @tipich: make
/understand work on Windows with pnpm 10.
- #121 — @Buzzwoo-Ecom-Team: customizable heading font.
- #117 — @DenisBalan: fix dashboard URL format in
vite.config.ts.
- #132 — @Xingkai98: file/class dual-view toggle.
- #142, #145 — @zhushen12580:
--language parameter and the documentation pass for it.
- #114 — fix tour navigation glitches across layers (incl.
TourFitView flicker, pending-focus-container reset, refit timeout no longer freezing).
- #112 / issue #102 — quadratic per-layer aggregations fixed (
O(N+K)); kills the slowdown on large graphs.
- #138 — git worktree path handling: skills now redirect
PROJECT_ROOT out of worktrees so they write to the main repo.
Other improvements
- Favicon matches homepage branding (6e0d1c1).
- Translated READMEs consolidated under
READMEs/ (b9ca060).
code-review-feedback pass for the --language PR (#145 stack).
Compat
- No graph schema changes since v2.5.0. Existing
.understand-anything/knowledge-graph.json files load unchanged.
- Install path: the new unified
install.sh / install.ps1 supersedes the per-platform installers. The old scripts still work but are no longer the documented path.
outputLanguage config key is now the single source of truth for both generated content and dashboard UI language.
Full changelog
v2.5.0...v2.7.3
详细ChangeLog
Highlights
Slide-up code panel with syntax highlighting; double-click a file node to open. Path-allowlisted via the dev server's /file-content.json endpoint, gated by an access token. Thanks @arkaigrowth for designing and shipping this!
Dashboard graph layout overhaul (#111)
Replaces dagre with ELK across all structural-style views and reshapes the layer-detail view around folder/community containers that lazy-expand on demand. Fixes the long-standing horizontal-sprawl problem where layers with 50+ nodes rendered as a single ~14000px row.
- Containers: layer-detail nodes are grouped by folder (Louvain community detection as fallback when folders are too flat). Each container renders as a translucent gold-bordered atom with the folder name and child count.
- Two-stage lazy layout: Stage 1 lays out container atoms only (~125ms even at 500 nodes). Stage 2 runs ELK per container on demand — when you click, when you zoom past 1.0, or when search/focus/tour lands a hit inside.
- Edge aggregation: cross-container edges collapse into a single weighted edge with count. Expanding a container inflates them back to file→file. Edges anchored to collapsed containers stay anchored to the container atom so nothing silently disappears.
- Visual overlays: containers light up for search hits (count badge), diff impact (red border), and focus/selection (gold border).
- Keyboard accessible: containers are real disclosure buttons (
role="button", aria-expanded, Enter/Space).
- Performance: dashboard main bundle stays at ~62KB gzipped (ELK split into a parallel-loaded chunk).
Other contributions since v2.3.1
Huge thanks to everyone who improved the project this cycle:
- #95 — @0xnayuta: harden plugin root resolution across install modes.
- #97 — @xiaolai: use
printf instead of echo to pipe TOOL_INPUT into grep.
- #98 — @xiaolai: log skipped invalid gitignore patterns to stderr.
- #103 — @ZebangCheng: fix hero image extension in the Astro homepage.
- #105 — @gustn99: README link refresh (Claude Code plugin).
- #110 — @LukasWana: file permissions on
extract-domain-context.py.
Other improvements
- File double-click also navigates the graph; sidebar composition preserved when reopening the slide-up code viewer.
- DomainGraphView migrated to ELK with LR direction preserved.
- WarningBanner now distinguishes graph data errors (asks your agent to fix the JSON) from dashboard rendering bugs (links to the issue tracker).
Compat
- No graph schema changes. Existing
.understand-anything/knowledge-graph.json files load unchanged.
applyDagreLayout is @deprecated and slated for removal next release.
Full changelog
v2.3.1...v2.5.0
详细ChangeLog
What's New
/understand-knowledge — Knowledge Base Analysis
New skill for analyzing Karpathy-pattern LLM wiki knowledge bases. Detects raw sources and wiki markdown with wikilinks, then produces interactive knowledge graphs with entity extraction, implicit relationships, and topic clustering across five phases (DETECT → SCAN → ANALYZE → MERGE → SAVE).
Comes with two new agents:
- article-analyzer — extracts implicit knowledge from wiki articles: entities (people, tools, papers), claims (decisions, assertions), and semantic edges (
builds_on, contradicts, exemplifies, authored_by, cites)
- assemble-reviewer — post-merge quality reviewer that recovers dropped nodes/edges, remaps unknown types, and verifies cross-batch consistency
A dedicated KnowledgeGraphView dashboard component provides force-directed visualization with search, tour highlighting, and relationship-typed edge styling.
.understandignore Support
User-configurable file exclusion for /understand analysis:
- IgnoreFilter — runtime filtering with hardcoded defaults (node_modules, build outputs, lock files, binaries) plus layered
.understandignore files from .understand-anything/ and project root
- IgnoreGenerator — auto-generates a starter
.understandignore by parsing your existing .gitignore and detecting project directories
- New Phase 0.5 in the
/understand workflow pauses for user confirmation after generating the ignore file
/understand Pipeline Improvements
- Subdomain graph merging (Phase 0) — merges multiple domain-specific graphs into one unified graph with deduplication
- Batch graph merging — new Python script with ID normalization, complexity mapping, and detailed fix reports
- Incremental updates — structural fingerprinting with
--auto-update / --no-auto-update flags
- Language/framework context injection for architecture analysis
- Expanded review paths — inline validation vs. full LLM review via
--review
Schema & Type Expansion
- Node types expanded from 13 → 21 (added
domain, flow, step, article, entity, topic, claim, source)
- Edge types expanded to 35 covering structural, behavioral, data flow, dependency, semantic, infrastructure, domain, and knowledge relationships
- Type aliases for flexible input (
func → function, doc → document, etc.)
Project Scanner Improvements
- Now handles non-code files (configs, docs, infrastructure, data) with explicit
fileCategory assignment
- Deterministic script-based file discovery with improved language and framework detection
Documentation & Internationalization
- Korean (
README.ko-KR.md) and Spanish (README.es-ES.md) README translations
- Animated showcase GIFs for structural and domain views
- Multi-platform badges (Codex, Copilot, Gemini CLI, OpenCode)
Fixes
- Dashboard URL now includes access token
- Connected edges highlight correctly on node selection
- Stable layout and scoped infrastructure filter in graph view
- Marketplace JSON schema validation fixes
- Edge weight coercion for graph merge scripts
详细ChangeLog
What's New in v2.1.0
Business Domain Knowledge Graph
A brand new domain graph view that maps your codebase's business logic — domains, flows, and process steps — so you can understand what the software does alongside how it's built.
- New
/understand-domain skill extracts business domain knowledge using a dedicated domain-analyzer agent
- Domain graph view in the dashboard with a view mode toggle pill to switch between architecture and domain graphs
- Custom node components:
DomainClusterNode, FlowNode, StepNode with domain-aware NodeInfo sidebar
- Domain overview and detail drill-down views with auto-widened spacing for long edge labels
- New core types:
domain, flow, step node types and domain-specific edge types
saveDomainGraph / loadDomainGraph persistence functions in core
Bug Fixes
- Missing node types in layer detail view — function/class nodes now correctly appear in layer detail (#65, #66)
- Deterministic node ID normalization — parallel batch analyzer output now produces consistent IDs regardless of execution order (#65)
- All 13 node types handled — edge cross-variant resolution and dropped edge traceability for generated graphs (#65)
- Step ID normalization improved with additional test coverage
- Redundant bottom bar (CodeViewer) no longer appears on node click (#55)
- POSIX-compatible hooks — replaced bash herestring with POSIX pipe for broader shell support (#64)
- 24 prompt engineering audit issues fixed across all 7 agents
- 8 dashboard audit issues addressed across components
New Platform Support
- VS Code + GitHub Copilot agent skills support (#52)
Dashboard Enhancements
- PNG export fix: replaced
foreignObject with clean SVG primitives (#50)
- Node type filters, path finder, and tooltips (#50)
- Header legends now horizontally scrollable on overflow
Other
- CI: added PR workflow for build, test, and type-check
- Prompt templates moved into agent definitions for prompt integrity
- Docs updated across all README translations
Community Contributors
Full Changelog: v2.0.0...v2.1.0
详细ChangeLog
What's New in v2.0.0
Beyond Code — Analyze Your Entire Project
Understand Anything now analyzes every file in your project, not just source code. Configs, docs, schemas, infrastructure — everything gets mapped into your knowledge graph.
26 New File Types
Infrastructure & DevOps: Dockerfile, Docker Compose, Kubernetes manifests, Terraform (HCL), GitHub Actions, Jenkinsfile, Makefile, Shell scripts, PowerShell, Batch
Data & Schema: SQL, GraphQL, Protobuf, JSON, JSON Schema, OpenAPI, YAML, TOML, XML, CSV, .env
Documentation: Markdown, reStructuredText, HTML, CSS, Plaintext
8 New Node Types
config · document · service · table · endpoint · pipeline · schema · resource
8 New Edge Types
deploys · serves · migrates · documents · provisions · routes · defines_schema · triggers
12 Custom Parsers
Structural parsers for Dockerfile, .env, GraphQL, JSON, Makefile, Markdown, Protobuf, Shell, SQL, Terraform, TOML, and YAML — extracting sections, definitions, services, endpoints, and references without tree-sitter.
Dashboard Enhancements
- Node type category filter controls
- File type breakdown in ProjectOverview
- New node/edge type support in NodeInfo sidebar
- 8 new node type colors across all theme presets
- Code viewer overlay height reduced to avoid blocking graph nodes
Agent Pipeline Updates
- All 5 agents updated for non-code file analysis
- Language context snippets for 11 non-code file types
- Type-aware analysis prompts for accurate non-code understanding
Full Changelog: v1.3.0...v2.0.0
详细ChangeLog
What's New in v1.3.0
Hierarchical Lens-Based Graph Navigation (#44 — @fishinakleinbottle)
- Two-level overview/detail model: top-level layer clusters → drill into file-level detail
- Portal nodes: visual indicators of cross-layer dependencies with click-to-navigate
- Breadcrumb navigation: always know where you are; click to jump back
- Sidebar navigation history: trail of recently visited nodes
- Escape to overview: press
Esc from any layer detail view
memo() wrappers on custom nodes for render performance- Topology/visual separation — heavy dagre layout only on structural changes
Theme Preset System (#45 — @Lum1104)
- Curated theme presets with accent color customization
- ThemePicker popover in the dashboard header
- Light theme support with CSS variable injection
- Theme persisted to localStorage
- Hardcoded colors consolidated into CSS variables
Dashboard Robustness (#42 — @Lum1104)
- Permissive graph validation with tiered auto-fix pipeline
- User-friendly error banner on malformed graph data
- Messy graph test fixtures for development
~85% Token Cost Reduction (#47 — @Lum1104)
- Scanner pre-resolves imports →
importMap in scan-result.json
- Replaced
allProjectFiles with batchImportData in file-analyzer
- Slimmed Phase 4 (architecture) and Phase 5 (tour) payloads
- Removed language/framework addendums from Phase 2 batches
- Gated LLM graph-reviewer behind
--review flag; inline deterministic validation by default
- Increased batch size (5-10 → 20-30) and concurrency (3 → 5)
Auto-Update on Commit (#31 — @1AdityaX)
- Automatic knowledge graph updates triggered by commits
- Structural fingerprinting to detect meaningful changes
--auto-update flag for the understand skill
- New plugin-discovery and plugin-registry test suites
- Additional persistence and tree-sitter plugin tests
- Added vitest coverage dependency
- Token-based access control for dashboard endpoints
- Enhanced endpoint security for the dev server
Bug Fixes
- Fix review findings: sort mutation, injection protection, directory baseline, error handling (#33)
- Fix edge types, validator guards, prompt accuracy in understand skill (#47)
- Restore validation errors compatibility and reject malformed collections (#42)
Contributors
Full Changelog: v1.2.0...v1.3.0
详细ChangeLog
Understand Anything is an open-source tool that combines LLM intelligence with static analysis to produce interactive dashboards for understanding codebases.
Highlights
- Multi-agent analysis pipeline — Project scanner, file analyzer, architecture analyzer, tour builder, and graph reviewer work together to produce rich knowledge graphs
- Interactive dashboard — Dark luxury themed React Flow visualization with graph-first layout, fuzzy/semantic search, guided tours, and persona modes
- Language-agnostic analysis — Config-driven plugin registry supporting 12+ languages with framework detection (TypeScript, Python, Django, and more)
- Multi-platform support — Works with Claude Code, Cursor, OpenCode, Gemini CLI (Antigravity), and Pi Agent
- Diff mode — Visualize PR/diff changes overlaid on the knowledge graph
- Large graph performance — Web Worker-based dagre layout, zoom limits, auto-center, and optimized pan/zoom interactions
- Keyboard shortcuts — Navigate the dashboard efficiently with keyboard controls
Skills
/understand — Full multi-agent codebase analysis/understand-dashboard — Launch the interactive visualization/understand-chat — Chat with your codebase context/understand-diff — Analyze PRs and diffs/understand-explain — Deep-dive file analysis/understand-onboard — Generate team onboarding guides
Contributors
Thanks to all contributors who made this release possible:
详细ChangeLog
