Understand-Anything

Merge branch 'main' into feat/language-agnostic-understanding

Lum1104 · 2026-03-24 23:46:13 +08:00

c7460f3189

Merge pull request #23 from mengdehong/main

fix(dashboard): optimize pan/zoom performance for large graphs

Yuxiang Lin · 2026-03-24 21:35:13 +08:00

684f4f16be

fix(dashboard): optimize pan/zoom interaction performance

- Widen transition to [box-shadow,outline,opacity,filter] to exclude
  transform (the pan/zoom culprit) while preserving ring animations
  (Tailwind v4 outline) and diff-fade opacity/filter transitions
- Replace inline boxShadow with Tailwind shadow-[] utility so
  .node-glow/.diff-*-glow CSS classes compose correctly
- Disable nodesDraggable, nodesConnectable, edgesFocusable,
  edgesReconnectable, elementsSelectable for read-only visualization

mengdehong · 2026-03-24 20:30:56 +08:00

b8d88023a5

chore: bump version to 1.2.0 and sync all plugin manifests

- Sync .claude-plugin/plugin.json (was stuck at 1.1.0) and .cursor-plugin/plugin.json (was 1.0.5) to match main version
- Update CLAUDE.md versioning section to list all four files that must be kept in sync
- Document scripts/generate-large-graph.mjs in CLAUDE.md

Lum1104 · 2026-03-24 20:26:31 +08:00

d697aefa53

Merge pull request #18 from AnnulusLabs/fix/large-graph-dashboard-perf

fix: move dagre layout to Web Worker for large graphs

Yuxiang Lin · 2026-03-24 20:15:43 +08:00

ed16da7e12

fix: keyboard shortcuts bugs and add shortcut hint

- Fix ? shortcut: add shiftKey: true so it matches on standard keyboards
- Fix Escape: keep hook always enabled so ESC closes the modal
  (remove dead showKeyboardHelp branch, read all state at invocation time)
- Fix formatShortcutKey: don't show redundant ⇧ for shifted punctuation
- Remove stale showKeyboardHelp from useMemo deps
- Add "Press ? for keyboard shortcuts" hint in graph area

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-24 10:19:31 +08:00

cd8cd0fb5c

Merge branch 'feat/keyboard-shortcuts-and-contributing' of https://github.com/berkcangumusisik/Understand-Anything into feat/keyboard-shortcuts-and-contributing

Berkcan Gümüşışık · 2026-03-23 19:58:34 +03:00

dbd761d72d

Refactor keyboard shortcuts; add Turkish README

Use dashboard store state at handler runtime and simplify shortcut wiring to avoid stale closures. App.tsx: replace many useDashboardStore selectors with runtime getState() calls inside keyboard shortcut actions and reduce useMemo dependencies to showKeyboardHelp. KeyboardShortcutsHelp.tsx: remove local Escape key effect (handled globally). useKeyboardShortcuts.ts: ignore shortcuts while typing in inputs/textareas/contentEditable (allow Escape), and improve Mac detection via userAgentData.platform fallback; use the same isMac flag in formatShortcutKey. README (zh-CN & ja-JP): add link to Turkish README (README.tr-TR.md).

Berkcan Gümüşışık · 2026-03-23 19:58:29 +03:00

6723ff3ea5

fix: move dagre layout to Web Worker for large graphs

Fixes #14 — dashboard becomes unusable with large knowledge graphs (2,700+ nodes).

- Web Worker for dagre layout: graphs above 200 nodes compute layout off the
  main thread via a dedicated Web Worker, keeping the UI responsive
- Request ID correlation: concurrent layout calls are routed by incrementing
  request ID, preventing race conditions where results cross-wire
- Worker error handling: onerror rejects pending promises; GraphView catches
  errors and clears the loading spinner
- Cancellation cleanup: effect cleanup clears layouting state to prevent
  stuck spinners when the graph switches below the async threshold
- Topology/visual split: dagre only re-runs when graph structure changes;
  node selection, tour highlights, and search results are applied as a
  cheap O(n) overlay without triggering relayout
- React.memo on CustomNode: prevents O(n) re-renders when selecting
  individual nodes in large graphs
- Zero overhead for small graphs: below 200 nodes, the original synchronous
  layout path is used unchanged

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

AnnulusLabs · 2026-03-23 10:37:12 -06:00

7bfcba677b

fix: address PR review feedback (C1-C4, I1-I5)

Critical fixes:
- C1: Remove unused treeSitter.nodeTypes from configs and schema — extraction
  logic is TS/JS-specific, nodeTypes gave false impression of generality
- C2+C3: Remove blocking temp dir prompt, default to .understand-anything/tmp/,
  update all 5 prompt templates to use project-local paths instead of /tmp/
- C4: Fix false-positive framework detection — use "next": (with quotes) for
  Next.js, remove cors/body-parser from Express keywords

Important fixes:
- I1: Change FrameworkConfig.language to languages[] array — React/Express/Vue
  now correctly listed under both typescript and javascript
- I2: Fix getByExtension case sensitivity — .TS now resolves same as .ts
- I3: languageKeyFromPath returns null instead of throwing for unknown extensions
- I4: Duplicate framework registration is now a no-op instead of corrupting array
- I5: SKILL.md now says "skip silently" when language/framework snippet not found

Also: getForLanguage returns a defensive copy, 3 new tests added (157 total).

Sreeram · 2026-03-23 21:53:02 +05:30

ae898a28b2

Merge branch 'Lum1104:main' into feat/keyboard-shortcuts-and-contributing

Berkcan Gümüşışık · 2026-03-23 15:59:03 +03:00

59b755ca46

fix: ask user for temp directory and improve prompt discovery

- Add blocking step in Phase 0 asking where to write temp files
  ($PROJECT_ROOT/.understand-anything/tmp/ or /tmp/), with explicit
  STOP-and-wait language to prevent premature execution
- Make language/framework file discovery explicit in Phase 2 and
  Phase 4 with concrete path examples and ls fallback, fixing
  issue where Claude's Search tool couldn't find files in subdirs
- Clean up $TMP_DIR alongside intermediate files in Phase 7

Sreeram · 2026-03-23 15:00:18 +05:30

42074bb210

Add keyboard shortcuts UI and CONTRIBUTING.md

Introduce keyboard shortcuts to the dashboard and add contributor docs. Adds a reusable useKeyboardShortcuts hook (with formatShortcutKey), a KeyboardShortcutsHelp modal component, and integrates shortcuts into App.tsx (registering keys like ?, Escape, /, ArrowLeft/Right, l, d and wiring store actions). Adds related styles (.glass-heavy, .kbd) to index.css. Also adds a comprehensive CONTRIBUTING.md with setup, workflow, testing, and PR guidelines.

Berkcan Gümüşışık · 2026-03-23 12:04:02 +03:00

b0cb17793a

refactor: unify skills install method across all platforms

Replace platform-specific install approaches with a consistent
per-skill symlink pattern for OpenCode and Codex (both share
~/.agents/skills/), matching the OpenCode docs requirement of
<name>/SKILL.md discovery.

Changes:
- OpenCode: migrate from opencode.json plugin config to direct
  skill symlinks in ~/.agents/skills/<name>/
- Codex: replace broken bundle symlink (understand-anything/ had
  no SKILL.md at root) with individual per-skill symlinks, matching
  OpenCode exactly
- All platforms: add universal ~/.understand-anything-plugin symlink
  so understand-dashboard SKILL.md can reliably find packages/dashboard/
- All platforms: use idempotent [ -e ] || [ -L ] || ln -s guard to
  handle multi-platform installs on the same machine
- All platforms: use ln -sf and rm -f for robust re-installs and
  partial uninstalls
- understand-dashboard/SKILL.md: replace fragile dirname-based path
  resolution with a prioritized candidate loop with explicit error
  guard
- Remove orphaned .opencode/plugins/understand-anything.js and its
  build scaffolding
- Update all three README variants (en, zh-CN, ja-JP) to reflect
  new OpenCode AI-driven install method

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-23 16:41:29 +08:00

c8d92444e2

feat: language-agnostic analysis with config-driven registry and framework detection

Replace the TypeScript/JavaScript-biased analysis pipeline with a truly
language-agnostic system. The core architecture was already language-neutral
(graph schema, dashboard, search) — the bias lived in agent prompts,
tree-sitter plugin, and language-lesson system.

Core changes:
- LanguageConfig + FrameworkConfig types with Zod validation
- LanguageRegistry (12 languages) and FrameworkRegistry (10 frameworks)
- Config-driven TreeSitterPlugin replacing hardcoded TS/JS grammars
- PluginRegistry now delegates to LanguageRegistry for extension mapping
- Language-lesson system uses config for display names and concepts

Prompt system:
- SKILL.md generalized: dynamic injection of language snippets and
  framework addendums instead of hardcoded if/else conditionals
- 12 language prompt snippets (languages/*.md) with concepts, patterns,
  frameworks per language
- 10 framework addendums (frameworks/*.md) with canonical file roles,
  edge patterns, architectural layers — Django/FastAPI/Flask preserved
  and split, plus React/Next.js/Express/Vue/Spring/Rails/Gin added
- Extended entry points, directory patterns, and test patterns across
  all 12 language ecosystems in base prompts

Sreeram · 2026-03-23 12:35:09 +05:30

b5eb2e6041

feat: extend analysis pipeline for Python codebases and frameworks

- project-scanner: detect Python frameworks from requirements.txt,
  pyproject.toml, setup.py, Pipfile (django, fastapi, flask, sqlalchemy,
  celery, pydantic, etc.); add pyproject.toml to project name extraction

- SKILL.md: expand Python entry points (manage.py, app.py, wsgi.py,
  asgi.py, run.py, __main__.py); add FastAPI and Flask framework guidance
  to Phase 2 and Phase 4 inline hints; wire addendum file injection for
  Django, FastAPI, and Flask when detected

- architecture-analyzer: add __init__.py and manage.py as entry-point
  file-level patterns; add Python directory patterns (migrations, signals,
  serializers, management, templatetags); clarify *.d.ts is TS-only

- tour-builder: add Python entry point filename patterns to +3 scoring
  (manage.py, app.py, wsgi.py, asgi.py, run.py, __main__.py)

- file-analyzer: add __init__.py barrel/entry-point detection alongside
  index.ts; show Python script execution alternative in example

- new: django-analyzer-addendum.md — canonical file roles, edge patterns
  (URL routing graph, signal wiring, ORM relationships), layer guide, and
  language lesson patterns for Django projects

- new: fastapi-analyzer-addendum.md — canonical file roles, DI tree edge
  patterns, layer guide, and language lesson patterns for FastAPI and Flask

- new: PYTHON-SUPPORT-CHANGES.md — reviewer doc covering every change,
  rationale, regression risk, and a testing checklist

https://claude.ai/code/session_015ihoTRnr7yYx3TkcadKYbn

Claude · 2026-03-21 16:00:03 +00:00

46fb114b14

chore: bump version to 1.1.1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-21 23:08:56 +08:00

8134bb95ca

fix: add zoom limits and auto-center for large graphs

- Set minZoom to 0.01 so fit-view works on graphs with hundreds of nodes
- Add TourFitView to pan/zoom to highlighted nodes during guided tours
- Add SelectedNodeFitView to center graph on node selected via search
- Wrap GraphView in ReactFlowProvider to enable useReactFlow() hooks

Thanks to @blackboxaicode for the insight on these improvements.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-21 23:07:58 +08:00

7c638603c0

fix: consolidate triple normalization into ordered Phase 4/5 steps

The original commit 9fe003a introduced normalization logic in three
separate places (Phase 4 inline, Phase 5 inline, Phase 5.5), creating
an ordering conflict where "do not use field X" rules appeared before
"convert field X to field Y" rules. An LLM following instructions
sequentially could drop legacy fields before converting them.

- Consolidate all layer normalization into Phase 4 as ordered steps
- Consolidate all tour normalization into Phase 5 as ordered steps
- Remove redundant Phase 5.5 entirely
- Fix misleading "from current prompt" comments about envelope format
- Add defensive handling for nodes-as-objects edge case
- Wrap JSON examples in arrays for visual consistency with prompts

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-21 22:59:36 +08:00

b8e605eafb

fix: ensure core is built before launching dashboard in /understand-dashboard

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-21 22:25:21 +08:00

de66bb7d76

feat: Align understand skill outputs with dashboard graph schema better

Lum1104 · 2026-03-20 00:14:23 +08:00

9fe003a977

docs: add star history and bump version to 1.1.0

Lum1104 · 2026-03-19 23:48:26 +08:00

54259f3b86

refactor: move platform config directories to repo root for discovery

Move .codex/, .opencode/, .openclaw/ from understand-anything-plugin/ to
repo root so each AI coding platform discovers its config at the standard
location. Delete .cursor/ (replaced by .cursor-plugin/plugin.json in next
commit). Plugin source code stays inside understand-anything-plugin/.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-19 23:15:00 +08:00

0f2b710992

fix: address code review feedback — terminology consistency and URL path

- Replace "agent" with "subagent" in SKILL.md dispatch references (5 locations)
- Add node_modules/.git/dist exclusions to Phase 0 find command
- Fix design doc URL to include understand-anything-plugin/ prefix

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-19 11:18:39 +08:00

4ea55cd6fc

feat: add per-platform INSTALL.md for AI-driven installation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-19 10:51:43 +08:00

aa4df6e987

refactor: update SKILL.md to dispatch subagents with context injection

Replace all named agent dispatches (project-scanner, file-analyzer,
architecture-analyzer, tour-builder, graph-reviewer) with subagent
dispatches using prompt template files. Add context injection for each
phase including README content, package manifest, directory tree,
framework-specific guidance, and cross-validation data.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-19 10:35:38 +08:00

2a01d3cc77

feat: add knowledge-graph-guide agent for graph navigation and querying

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-19 10:32:03 +08:00

84d0462e20

refactor: move pipeline agents into skills/understand/ as prompt templates

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-19 10:31:22 +08:00

5e85a23aa2

Merge pull request #3 from Lum1104/feature/diff-mode

perf(dashboard): skip diff overlay computation when diffMode is off

Yuxiang Lin · 2026-03-17 11:59:15 +08:00

6c38510acb

Merge pull request #2 from KyleWMiller/feature/diff-mode

Diff Mode

Yuxiang Lin · 2026-03-17 11:55:10 +08:00

988e73f249

perf(dashboard): skip diff overlay computation when diffMode is off

Guard diffNodeIds construction and per-edge lookups behind diffMode
check to avoid unnecessary Set spreads and has() calls on every
graph recompute when diff mode is inactive.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-17 11:53:08 +08:00

4161d3eba3

fix(graph-reviewer): remove duplicated critical checks from warning section

Edge weights, node ID prefix conventions, and tag formatting were listed
in both Check 1 (Schema Validation — Critical) and Check 7 (Quality —
Warning). A deterministic script following check headings would classify
these as warnings, potentially approving invalid graphs. Remove the
duplicates from Check 7 since Check 1 already covers them as critical.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-17 11:28:29 +08:00

70b4e6fe0a

fix(agents): define .sh as supported source extension in project-scanner

The exclusion rule conditionally kept .sh files for bash-first projects,
but the source-file whitelist and language mapping table had no .sh entry,
causing retained shell files to be dropped or untyped. Add .sh/.bash to
the whitelist and language table (mapped to 'bash'), and remove the
conditional exclusion rule.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-17 11:13:18 +08:00

3715552875

fix(graph-reviewer): align duplicate-ID classification as critical

Duplicate node IDs were listed under Check 6 (Warning) but classified as
critical in the Severity Classification section. A script following check
headings would classify duplicates as warnings, letting invalid graphs
pass review. Move duplicate-ID check to its own Check 5 (Critical) and
renumber subsequent checks.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-17 11:12:29 +08:00

f5b9eb7d61

chore: bump version to 1.0.5

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-17 11:10:14 +08:00

b9b48466c3

feat: diff mode added

Kyle Miller · 2026-03-16 16:40:19 -07:00

da8509e2b1

feat(agents): add script-augmented two-phase architecture to all agents

Redesign all 5 agent prompts with a "Phase 1 — Script" + "Phase 2 — LLM
Reasoning" structure. Agents now write and execute scripts for deterministic
work (validation, file discovery, structure extraction, graph analysis)
before applying LLM judgment for semantic tasks (summaries, tags, pedagogy).

Key changes per agent:
- graph-reviewer: script performs all 6 validation checks deterministically
- project-scanner: script handles file discovery, language detection, line counting
- file-analyzer: script extracts functions/classes/imports via regex patterns
- architecture-analyzer: script computes import adjacency, inter-group frequency
- tour-builder: script calculates fan-in, BFS traversal, cluster detection

Design safeguards:
- scriptCompleted sentinel field guards against partial script output
- Batch-indexed temp paths prevent collision in concurrent file-analyzer agents
- Explicit "trust the script" directives prevent LLM from re-reading raw data
- Up to 2 script retries on failure
- Explicit instructions to strip intermediate fields from final output
- Bash tool added to all agent tool lists

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Lum1104 · 2026-03-16 18:17:02 +08:00

6af00c5f85

fix(dashboard): enable click and expand for all node types (function, class, etc.)

Previously only FILE nodes responded to clicks with the code viewer overlay.
Now all node types open the detail viewer on click. Also added a direct click
handler on CustomNode to fix click events not firing for child nodes inside
group layers on Windows.

Bump version to 1.0.4.

Lum1104 · 2026-03-16 14:34:11 +08:00

b82efea88e

fix: resolve plugin installation failures for workspace resolution and missing dependencies

Add Vite resolve aliases for core subpath exports (schema, search, types)
to fix import resolution on Windows where Node.js package exports are not
properly followed by Vite's import analysis.

Bump version to 1.0.3.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-16 12:23:48 +08:00

5c0afb35ff

fix: resolve plugin installation failures for workspace resolution and missing dependencies

- Add pnpm-workspace.yaml to plugin distribution so workspace:* deps resolve on install
- Add devlop and hast-util-to-jsx-runtime as explicit dashboard dependencies (pnpm strict hoisting)
- Make tsconfig.json files self-contained to work outside monorepo root
- Add prepare script to auto-build core package after pnpm install
- Bump version to 1.0.2

Lum1104 · 2026-03-15 19:12:55 +08:00

bdf6cf6856

fix: remove nested .claude-plugin/plugin.json to fix user-scope marketplace installation

The nested plugin.json inside understand-anything-plugin/.claude-plugin/
conflicted with the root marketplace.json, causing Claude Code to fail
when installing the plugin in user scope with "Source path does not exist" error.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-15 17:21:02 +08:00

99840b16a0

feat: redesign dashboard with dark luxury theme, improve agent pipeline

- Remove ChatPanel and @anthropic-ai/sdk dependency (redundant with /understand-chat)
- Replace Monaco editor with styled summary code viewer
- New graph-first layout: 75% graph + 360px right sidebar
- Dark luxury aesthetic: deep blacks, gold/amber accents, DM Serif Display typography
- Add ProjectOverview component for sidebar default state
- Learn persona now shows tour panel directly in sidebar
- Add schema validation on graph load with error banner
- Defensive null checks in store for tour methods
- Agent pipeline: write intermediate results to disk instead of context
- Agent models: sonnet for simple tasks, opus for complex (no haiku)
- Prompt-engineer all 5 agent prompts and SKILL.md
- Auto-trigger /understand-dashboard after /understand completes
- Add dashboard screenshot to README
- Bump version to 1.0.1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-15 12:36:39 +08:00

343e94c9a7

feat(skill): add smart graph reading protocol to query skills

Replace "read the whole graph file" instructions with targeted Grep-based
reading in /understand-chat, /understand-diff, /understand-explain, and
/understand-onboard. Each skill now includes a Graph Structure Reference
and extracts only the relevant subgraph (matched nodes + 1-hop edges)
instead of dumping the entire JSON into context. Also update /understand
to reference /understand-dashboard.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-15 11:16:55 +08:00

00d9919ba3

feat(skill): add /understand-dashboard skill to launch visualization

New skill command that starts the Vite dev server to visualize the
knowledge graph in a web dashboard.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-15 11:16:48 +08:00

fe50941da4

refactor: restructure monorepo into Claude Code plugin layout

Move packages/{core,dashboard,skill} into understand-anything-plugin/ to
conform to the Claude Code plugin format. Add .claude-plugin/marketplace.json
for plugin discovery. Update workspace config and docs accordingly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Lum1104 · 2026-03-15 11:16:43 +08:00

b75235919e

45 Commits