Understand Anything

https://github.com/egonex-ai/understand-anything
Admin
Understand Anything is an open-source tool that analyzes codebases and knowledge bases to produce...
Tokens:498,921
Snippets:2,953
Trust Score:5.6
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### buildOnboardingGuide: Generate markdown onboarding guide from knowledge graph

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

Defines the buildOnboardingGuide function that takes a KnowledgeGraph and returns a markdown string. It generates sections for project overview, architecture, key concepts, getting started tour, file map, complexity hotspots, and a footer. The output is standalone markdown suitable for README, wiki, or docs.

```typescript
// packages/skill/src/onboard-builder.ts
import type { KnowledgeGraph } from "@understand-anything/core";

/**
 * Generate a structured onboarding guide from the knowledge graph.
 * Output is standalone markdown suitable for a README, wiki, or docs.
 */
export function buildOnboardingGuide(graph: KnowledgeGraph): string {
  const { project, nodes, edges, layers, tour } = graph;
  const lines: string[] = [];

  // --- Project Overview ---
  lines.push(`# ${project.name}`);
  lines.push("");
  lines.push(`> ${project.description}`);
  lines.push("");
  lines.push(`| | |`);
  lines.push(`|---|---|`);
  lines.push(`| **Languages** | ${project.languages.join(", ")} |`);
  lines.push(`| **Frameworks** | ${project.frameworks.join(", ")} |`);
  lines.push(`| **Components** | ${nodes.length} nodes, ${edges.length} relationships |`);
  lines.push(`| **Last Analyzed** | ${project.analyzedAt} |`);
  lines.push("");

  // --- Architecture ---
  if (layers.length > 0) {
    lines.push("## Architecture");
    lines.push("");
    lines.push("The project is organized into the following layers:");
    lines.push("");
    for (const layer of layers) {
      const memberNames = layer.nodeIds
        .map((id) => nodes.find((n) => n.id === id)?.name)
        .filter(Boolean);
      lines.push(`### ${layer.name}`);
      lines.push("");
      lines.push(layer.description);
      lines.push("");
      if (memberNames.length > 0) {
        lines.push(`Key components: ${memberNames.join(", ")}`);
        lines.push("");
      }
    }
  }

  // --- Key Concepts ---
  const conceptNodes = nodes.filter((n) => n.type === "concept");
  if (conceptNodes.length > 0) {
    lines.push("## Key Concepts");
    lines.push("");
    lines.push("Important architectural and domain concepts to understand:");
    lines.push("");
    for (const concept of conceptNodes) {
      lines.push(`### ${concept.name}`);
      lines.push("");
      lines.push(concept.summary);
      lines.push("");
    }
  }

  // --- Getting Started (Tour) ---
  if (tour.length > 0) {
    lines.push("## Getting Started");
    lines.push("");
    lines.push("Follow this guided tour to understand the codebase:");
    lines.push("");
    for (const step of tour) {
      const stepNodes = step.nodeIds
        .map((id) => nodes.find((n) => n.id === id))
        .filter(Boolean);
      lines.push(`### ${step.order}. ${step.title}`);
      lines.push("");
      lines.push(step.description);
      lines.push("");
      if (stepNodes.length > 0) {
        lines.push("**Files to look at:**");
        for (const node of stepNodes) {
          if (node!.filePath) {
            lines.push(`- \`${node!.filePath}\` — ${node!.summary}`);
          }
        }
        lines.push("");
      }
      if (step.languageLesson) {
        lines.push(`> **Language Tip:** ${step.languageLesson}`);
        lines.push("");
      }
    }
  }

  // --- File Map ---
  const fileNodes = nodes.filter((n) => n.type === "file" && n.filePath);
  if (fileNodes.length > 0) {
    lines.push("## File Map");
    lines.push("");
    lines.push("| File | Purpose | Complexity |");
    lines.push("|------|---------|------------|");
    for (const node of fileNodes) {
      lines.push(`| \`${node.filePath}\` | ${node.summary} | ${node.complexity} |`);
    }
    lines.push("");
  }

  // --- Complexity Hotspots ---
  const complexNodes = nodes.filter((n) => n.complexity === "complex");
  if (complexNodes.length > 0) {
    lines.push("## Complexity Hotspots");
    lines.push("");
    lines.push("These components are the most complex and deserve extra attention:");
    lines.push("");
    for (const node of complexNodes) {
      lines.push(`- **${node.name}** (${node.type}): ${node.summary}`);
    }
    lines.push("");
  }

  // --- Footer ---
  lines.push("---");
  lines.push("");
  lines.push(`*Generated by [Understand Anything](https://github.com/anthropics/understand-anything) from knowledge graph v${graph.version}*`);
  lines.push("");

  return lines.join("\n");
}
```

--------------------------------

### Preview homepage with pnpm preview

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-15-homepage-implementation.md

Starts a local preview server for the homepage. Use it to verify that Nav, Hero, Showcase, Features, Install CTA, and Footer render correctly, scroll animations trigger, and the Nav becomes solid on scroll.

```bash
cd /Users/yuxianglin/Desktop/opensource/Understand-Anything/homepage
pnpm preview
```

--------------------------------

### Start Dashboard (Optional)

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Start the dashboard development server.

```bash
pnpm dev:dashboard
```

--------------------------------

### Install for Kiro CLI/IDE

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Runs the installer with the kiro platform. After installation, the skills are symlinked into ~/.kiro/skills/ and the understand agent is written to ~/.kiro/agents/understand.json; restart the IDE.

```bash
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s kiro
```

--------------------------------

### Install the plugin

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Install the Understand-Anything plugin using the marketplace commands. Requires a platform that supports the /plugin command.

```bash
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
```

--------------------------------

### Install Understand Anything plugin

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/specs/2026-03-15-homepage-design.md

Installation commands for the Understand Anything Claude Code plugin. Run these in Claude Code to add the plugin from the marketplace, install it, and then invoke the /understand command.

```text
/plugin marketplace add Egonex-AI/Understand-Anything
/plugin install understand-anything
/understand
```

--------------------------------

### One-line install for Windows (PowerShell)

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Downloads and runs the PowerShell installer. Clones to ~/.understand-anything/repo and creates symlinks; restart your CLI/IDE afterwards.

```powershell
iwr -useb https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.ps1 | iex
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Install project dependencies using pnpm.

```bash
pnpm install
```

--------------------------------

### One-line install for macOS/Linux (Codex, OpenCode, etc.)

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Downloads and runs the install script. Optionally pass a platform to skip the prompt. Clones to ~/.understand-anything/repo and creates symlinks; restart your CLI/IDE afterwards.

```bash
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash
# or skip the prompt by passing the platform:
curl -fsSL https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/main/install.sh | bash -s codex
```

--------------------------------

### Verify all format guides are present

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-09-understand-knowledge.md

Lists the format guide files in the skill's formats directory. Expected to include obsidian.md, logseq.md, dendron.md, foam.md, karpathy.md, zettelkasten.md, and plain.md.

```bash
ls understand-anything-plugin/skills/understand-knowledge/formats/
```

--------------------------------

### Install and build packages

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-05-24-semantic-batching-and-output-chunking-impl.md

Installs dependencies and builds the core and skill packages. Expected result is all commands succeed.

```bash
pnpm install
pnpm --filter @understand-anything/core build
pnpm --filter @understand-anything/skill build
```

--------------------------------

### Install via Copilot CLI plugin

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Installs the plugin for Copilot CLI using the plugin install command.

```bash
copilot plugin install Egonex-AI/Understand-Anything:understand-anything-plugin
```

--------------------------------

### TreeSitterPlugin implementation (setup)

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

Initial implementation of the TreeSitterPlugin. Sets up parsers for TypeScript and JavaScript, selects the parser based on file extension, and provides a recursive tree traversal helper. This is the start of the plugin that will implement the AnalyzerPlugin interface.

```typescript
import Parser from "tree-sitter";
import TypeScript from "tree-sitter-typescript";
import JavaScript from "tree-sitter-javascript";
import type {
  AnalyzerPlugin,
  StructuralAnalysis,
  ImportResolution,
  CallGraphEntry,
} from "../types.js";

const tsParser = new Parser();
tsParser.setLanguage(TypeScript.typescript);

const jsParser = new Parser();
jsParser.setLanguage(JavaScript);

function getParser(filePath: string): Parser {
  if (filePath.endsWith(".ts") || filePath.endsWith(".tsx")) return tsParser;
  return jsParser;
}

function traverse(
  node: Parser.SyntaxNode,
  callback: (node: Parser.SyntaxNode) => void,
): void {
  callback(node);
  for (let i = 0; i < node.childCount; i++) {
    traverse(node.child(i)!, callback);
  }
}
```

--------------------------------

### Install @anthropic-ai/sdk

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Installs the Anthropic SDK in the dashboard package. Run from the repository root.

```bash
cd packages/dashboard && pnpm add @anthropic-ai/sdk
```

--------------------------------

### Run pnpm install and build

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

Command to install dependencies and build the core package. Expected to compile with no errors and create packages/core/dist/.

```bash
cd /path/to/project && pnpm install && pnpm --filter @understand-anything/core build
```

--------------------------------

### Install dependencies and build Astro project

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-15-homepage-implementation.md

Installs dependencies and builds the Astro project. Expected output: build succeeds and a dist/ directory is created.

```bash
cd /Users/yuxianglin/Desktop/opensource/Understand-Anything/homepage
pnpm install
pnpm build
```

--------------------------------

### Commit format guides with git

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-09-understand-knowledge.md

Commands to stage and commit the new format guide files in the understand-knowledge skill directory.

```bash
git add understand-anything-plugin/skills/understand-knowledge/formats/
git commit -m "feat(skill): add 7 research-backed format guides for knowledge base parsing"
```

--------------------------------

### User command to fetch and follow INSTALL.md

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/specs/2026-03-18-multi-platform-simple-design.md

One-line command the user tells the agent to fetch and follow installation instructions from the specified URL.

```text
Fetch and follow instructions from https://raw.githubusercontent.com/Egonex-AI/Understand-Anything/refs/heads/main/understand-anything-plugin/.codex/INSTALL.md
```

--------------------------------

### Update final output example to include importMap

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-27-token-reduction-impl.md

JSON example for the final output, now including the importMap field.

```json
{
  "name": "project-name",
  "description": "...",
  "languages": ["typescript"],
  "frameworks": ["React"],
  "files": [...],
  "totalFiles": 42,
  "estimatedComplexity": "moderate",
  "importMap": {
    "src/index.ts": ["src/utils.ts"]
  }
}
```

--------------------------------

### Create a Branch

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Create a descriptive branch for your work, with examples for features, fixes, and documentation.

```bash
git checkout -b feat/my-feature        # For new features
git checkout -b fix/bug-description    # For bug fixes
git checkout -b docs/update-readme     # For documentation
```

--------------------------------

### Homepage commands

Source: https://github.com/egonex-ai/understand-anything/blob/main/homepage/README.md

Commands to run from the repository root: start the local dev server, build the static site, and preview the built site.

```bash
pnpm --filter homepage dev
```

```bash
pnpm --filter homepage build
```

```bash
pnpm --filter homepage preview
```

--------------------------------

### Persistence directory structure and metadata example

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/specs/2026-03-14-understand-anything-design.md

Shows the .understand-anything/ directory layout with the knowledge graph, meta.json containing analysis metadata, per-file cache, and tours. The meta.json example includes lastAnalyzedAt, gitCommitHash, version, and analyzedFiles fields.

```plaintext
.understand-anything/
├── knowledge-graph.json       # The full graph (committable)
├── meta.json                  # Analysis metadata
│   {
│     "lastAnalyzedAt": "2026-03-14T...",
│     "gitCommitHash": "abc123",
│     "version": "1.0.0",
│     "analyzedFiles": 47
│   }
├── cache/                     # Per-file analysis cache
│   ├── src__index.ts.json
│   └── src__auth__login.ts.json
└── tours/
    └── default-tour.json
```

--------------------------------

### Resolve plugin root and install dependencies

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md

Pre-flight script that locates the understand-anything plugin root by checking several candidate paths, verifies required files, and builds the core package if needed. Exits with an error if the root cannot be found. Requires pnpm; if missing, instructs the user to install Node.js ≥ 22 and pnpm ≥ 10.

```bash
SKILL_REAL=$(realpath ~/.agents/skills/understand 2>/dev/null || readlink -f ~/.agents/skills/understand 2>/dev/null || echo "")
SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand 2>/dev/null || readlink -f ~/.copilot/skills/understand 2>/dev/null || echo "")
COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")

PLUGIN_ROOT=""
for candidate in \
  "${CLAUDE_PLUGIN_ROOT}" \
  "$HOME/.understand-anything-plugin" \
  "$SELF_RELATIVE" \
  "$COPILOT_SELF_RELATIVE" \
  "$HOME/.codex/understand-anything/understand-anything-plugin" \
  "$HOME/.opencode/understand-anything/understand-anything-plugin" \
  "$HOME/.pi/understand-anything/understand-anything-plugin" \
  "$HOME/understand-anything/understand-anything-plugin"; do
  if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
    PLUGIN_ROOT="$candidate"
    break
  fi
done

if [ -z "$PLUGIN_ROOT" ]; then
  echo "Error: Cannot find the understand-anything plugin root."
  echo "Checked:"
  echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
  echo "  - $HOME/.understand-anything-plugin"
  echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand>}"
  echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand>}"
  echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
  echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
  echo "  - $HOME/understand-anything/understand-anything-plugin"
  echo "Make sure the plugin is installed correctly."
  exit 1
fi

if [ ! -f "$PLUGIN_ROOT/packages/core/dist/index.js" ]; then
  cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
fi
```

--------------------------------

### Generate starter .understandignore file

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md

Run when $UA_DIR/.understandignore does not exist before a full scan. Invokes the bundled script with PLUGIN_ROOT passed via env to avoid path issues for copied skill installs. Waits for user confirmation after generation.

```bash
PLUGIN_ROOT="$PLUGIN_ROOT" node "<SKILL_DIR>/generate-ignore.mjs" "$PROJECT_ROOT"
```

--------------------------------

### tour-builder-prompt.md input schema (before)

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-27-token-reduction-impl.md

Current input schema example in tour-builder-prompt.md, showing layers with nodeIds.

```json
{
  "nodes": [...],
  "edges": [...],
  "layers": [
    {"id": "layer:core", "name": "Core", "nodeIds": ["file:src/index.ts"]}
  ]
}
```

--------------------------------

### Install tree-sitter grammar packages

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-21-language-agnostic-plan.md

Installs ten tree-sitter grammar packages for Python, Go, Java, Rust, C++, C#, Ruby, PHP, Swift, and Kotlin using pnpm.

```bash
cd understand-anything-plugin && pnpm --filter @understand-anything/core add \
  tree-sitter-python \
  tree-sitter-go \
  tree-sitter-java \
  tree-sitter-rust \
  tree-sitter-cpp \
  tree-sitter-c-sharp \
  tree-sitter-ruby \
  tree-sitter-php \
  tree-sitter-swift \
  tree-sitter-kotlin
```

--------------------------------

### Install @dagrejs/dagre

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Installs the dagre library in the dashboard package. Run from the repository root; the command changes into the dashboard directory and adds @dagrejs/dagre as a dependency.

```bash
cd packages/dashboard && pnpm add @dagrejs/dagre
```

--------------------------------

### Verify full build with pnpm commands

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Run the full build and test suite for the core and skill packages, then start the dashboard dev server. All commands should pass or run without errors.

```bash
pnpm install
pnpm --filter @understand-anything/core build
pnpm --filter @understand-anything/skill build
pnpm --filter @understand-anything/core test
pnpm --filter @understand-anything/skill test
pnpm dev:dashboard
```

--------------------------------

### Format Detection Output Example

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-09-understand-knowledge.md

Example JSON output for the format-detector agent, showing an obsidian format with confidence and parsing hints.

```json
{
  "format": "obsidian",
  "confidence": 0.95,
  "parsingHints": {
    "linkStyle": "wikilink",
    "metadataLocation": "yaml-frontmatter",
    "folderSemantics": "none",
    "specialFiles": [".obsidian/app.json"],
    "tagSyntax": "hashtag-inline"
  }
}
```

--------------------------------

### Run skeleton against fixture: setup and execute

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-05-24-semantic-batching-and-output-chunking-impl.md

Commands to create a scratch directory, copy the fixture scan-result.json, and run compute-batches.mjs. Expected stderr shows 3 communities of size 3 each.

```bash
mkdir -p /tmp/ua-prototype/.understand-anything/intermediate
cp understand-anything-plugin/skills/understand/test/fixtures/scan-result-3-cliques.json \
   /tmp/ua-prototype/.understand-anything/intermediate/scan-result.json
node understand-anything-plugin/skills/understand/compute-batches.mjs /tmp/ua-prototype
```

--------------------------------

### Create README.md for Understand Anything

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

The README.md file for the project, providing an overview, features, quick start commands, project structure, and tech stack. It is intended to be created as part of the integration task.

```markdown
# Understand Anything

An open-source tool that combines LLM intelligence with static analysis to help anyone understand any codebase — from junior developers to product managers.

## Features

- **Knowledge Graph** — Automatically maps your codebase into an interactive graph of files, functions, classes, and their relationships
- **Multi-Panel Dashboard** — Graph view, code viewer, chat, and learn panels in a workspace layout
- **Natural Language Search** — Search your codebase with plain English: "which parts handle authentication?"
- **Tree-sitter Analysis** — Accurate structural analysis for TypeScript, JavaScript (more languages coming)
- **LLM-Powered Summaries** — Every node gets a plain-English description of what it does and why

## Quick Start

```bash
# Install dependencies
pnpm install

# Build the core package
pnpm --filter @understand-anything/core build

# Start the dashboard dev server
pnpm dev:dashboard
```

## Project Structure

```
packages/
  core/        — Analysis engine: types, persistence, tree-sitter, LLM prompts
  dashboard/   — React + TypeScript web dashboard
  skill/       — Claude Code skill (coming soon)
```

## Tech Stack

- TypeScript, pnpm workspaces
- React 18, Vite, TailwindCSS
- React Flow (graph visualization)
- Monaco Editor (code viewer)
- Zustand (state management)
- tree-sitter (static analysis)
```

--------------------------------

### tour-builder-prompt.md input schema (after)

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-27-token-reduction-impl.md

Updated input schema example with file-only nodes, imports edges, and slim layers without nodeIds.

```json
{
  "nodes": [
    {"id": "file:src/index.ts", "type": "file", "name": "index.ts", "filePath": "src/index.ts", "summary": "..."}
  ],
  "edges": [
    {"source": "file:src/index.ts", "target": "file:src/utils.ts", "type": "imports"}
  ],
  "layers": [
    {"id": "layer:core", "name": "Core", "description": "Core application logic"}
  ]
}
```

--------------------------------

### Install dependencies and verify WASM file resolution

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-15-language-extractors-impl.md

Runs pnpm install and a node command to verify that the tree-sitter-python WASM file resolves correctly.

```bash
pnpm install
node -e "const r=require('module').createRequire(import.meta.url??__filename); console.log(r.resolve('tree-sitter-python/tree-sitter-python.wasm'))"
```

--------------------------------

### Fallback: start Vite dev server

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md

Starts the Vite dev server for the dashboard, pointing at the project's knowledge graph. Requires PROJECT_DIR and DASHBOARD_DIR to be set. Runs in the background so the user can continue working.

```bash
: "${PROJECT_DIR:?Run step 1 first so PROJECT_DIR is set}"
: "${DASHBOARD_DIR:?Run step 5 first so DASHBOARD_DIR is set}"
cd "$DASHBOARD_DIR" && GRAPH_DIR="$PROJECT_DIR" npx vite --host 127.0.0.1
```

--------------------------------

### Example markdown language config

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-28-understand-anything-extension-impl.md

Shows the pattern for creating a language config file, using markdown.ts as an example. Each config follows the same structure as typescript.ts, with id, displayName, extensions, concepts, and filePatterns.

```typescript
// markdown.ts
import type { LanguageConfig } from "../types.js";

export const markdownConfig = {
  id: "markdown",
  displayName: "Markdown",
  extensions: [".md", ".mdx"],
  concepts: ["headings", "links", "code blocks", "front matter", "lists", "tables", "images"],
  filePatterns: {
    entryPoints: ["README.md"],
    barrels: [],
    tests: [],
    config: [],
  },
} satisfies LanguageConfig;
```

--------------------------------

### /understand-figma Usage Examples

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/specs/2026-06-24-understand-figma-foundation-design.md

Displayed usage lines for the /understand-figma skill: URL, bare key, page scope, and language options.

```bash
/understand-figma https://www.figma.com/file/<KEY>/<name>   # URL
/understand-figma <FILE_KEY>                                 # bare key
/understand-figma <KEY> --page "Onboarding"                  # scope to one page (optional)
/understand-figma <KEY> --language ko                        # reuse existing --language
```

--------------------------------

### Run skill package tests with pnpm

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Command to install dependencies and run the skill package tests. Expected to fail because the implementation files do not exist yet.

```bash
pnpm install && pnpm --filter @understand-anything/skill test
```

--------------------------------

### Kiro CLI usage command

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Starts a chat with the understand agent to analyze the project.

```bash
kiro-cli chat --agent understand "Analyze this project"
```

--------------------------------

### Run dashboard via Vite dev server

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Alternative for working from a clone: build the core package and start the Vite dev server with GRAPH_DIR pointing to the analyzed project. Requires pnpm.

```bash
pnpm install && pnpm --filter @understand-anything/core build, then GRAPH_DIR=/path/to/analyzed/project pnpm dev:dashboard
```

--------------------------------

### Create understand-onboard.md skill file

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

Markdown content for the skill file that defines the /understand-onboard command. It instructs the agent to read the knowledge graph, generate an onboarding guide, and offer to save it.

```markdown
---
name: understand-onboard
description: Generate a structured onboarding guide for new team members using the knowledge graph
---

# /understand-onboard

Generate a comprehensive onboarding guide from the project's knowledge graph.

## Instructions

1. Read the knowledge graph at `.understand-anything/knowledge-graph.json`
2. If it doesn't exist, tell the user to run `/understand` first
3. Generate a structured onboarding guide that includes:
   - Project overview (name, languages, frameworks, description)
   - Architecture layers and their responsibilities
   - Key concepts to understand
   - Guided tour (step-by-step walkthrough)
   - File map (what each key file does)
   - Complexity hotspots (what to be careful with)
4. Format as clean markdown
5. Offer to save the guide to `docs/ONBOARDING.md` in the project
6. Suggest the user commit it to the repo for the team

```

--------------------------------

### Generated .understandignore file format

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/specs/2026-04-10-understandignore-design.md

Example output of the generator, showing the header comment, built-in defaults, and commented-out suggestions. All lines are commented out by default; users must uncomment to activate.

```plaintext
# .understandignore — patterns for files/dirs to exclude from analysis
# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)
# Lines below are suggestions — uncomment to activate.
# Use ! prefix to force-include something excluded by defaults.
#
# Built-in defaults (always excluded unless negated):
#   node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, *.min.js, etc.
#

# --- Suggested exclusions (uncomment to activate) ---

# Test files
# __tests__/
# *.test.*
# *.spec.*

# Test data
# fixtures/
# testdata/

# Documentation
# docs/

# ... (more suggestions based on detection)
```

--------------------------------

### Fallback: install dashboard dependencies

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md

Installs dashboard dependencies with pnpm, preferring a frozen lockfile. Requires PLUGIN_ROOT to be set. Falls back to a regular install if the frozen install fails.

```bash
: "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"
DASHBOARD_DIR="${DASHBOARD_DIR:-$PLUGIN_ROOT/packages/dashboard}"
cd "$DASHBOARD_DIR" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install)
```

--------------------------------

### Build core if missing

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand-figma/SKILL.md

Builds the core package if the Figma index file is missing. Uses pnpm with a frozen lockfile, falling back to a regular install if that fails.

```bash
cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
```

--------------------------------

### generateStarterIgnoreFile: Create starter .understandignore file

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-10-understandignore-impl.md

Generates a starter .understandignore file by scanning the project root for common directories (e.g., __tests__, test, docs) and suggesting them as commented-out exclusions. All suggestions are commented out; the user must uncomment to activate. Always includes generic test file patterns like *.test.*, *.spec.*, and *.snap.

```typescript
import { existsSync } from "node:fs";
import { join } from "node:path";

const HEADER = `# .understandignore — patterns for files/dirs to exclude from analysis
# Syntax: same as .gitignore (globs, # comments, ! negation, trailing / for dirs)
# Lines below are suggestions — uncomment to activate.
# Use ! prefix to force-include something excluded by defaults.
#
# Built-in defaults (always excluded unless negated):
#   node_modules/, .git/, dist/, build/, bin/, obj/, *.lock, *.min.js, etc.
#
`;

/** Directories to check for and suggest excluding. */
const DETECTABLE_DIRS = [
  { dir: "__tests__", pattern: "__tests__/" },
  { dir: "test", pattern: "test/" },
  { dir: "tests", pattern: "tests/" },
  { dir: "fixtures", pattern: "fixtures/" },
  { dir: "testdata", pattern: "testdata/" },
  { dir: "docs", pattern: "docs/" },
  { dir: "examples", pattern: "examples/" },
  { dir: "scripts", pattern: "scripts/" },
  { dir: "migrations", pattern: "migrations/" },
  { dir: ".storybook", pattern: ".storybook/" },
];

/** Always-included generic suggestions. */
const GENERIC_SUGGESTIONS = [
  "*.test.*",
  "*.spec.*",
  "*.snap",
];

/**
 * Generates a starter .understandignore file by scanning the project root
 * for common directories and suggesting them as commented-out exclusions.
 *
 * All suggestions are commented out — the user must uncomment to activate.
 * Returns the file content as a string.
 */
export function generateStarterIgnoreFile(projectRoot: string): string {
  const sections: string[] = [HEADER];

  // Detected directory suggestions
  const detected: string[] = [];
  for (const { dir, pattern } of DETECTABLE_DIRS) {
    if (existsSync(join(projectRoot, dir))) {
      detected.push(pattern);
    }
  }

  if (detected.length > 0) {
    sections.push("# --- Detected directories (uncomment to exclude) ---\n");
    for (const pattern of detected) {
      sections.push(`# ${pattern}`);
    }
    sections.push("");
  }

  // Generic suggestions (always included)
  sections.push("# --- Test file patterns (uncomment to exclude) ---\n");
  for (const pattern of GENERIC_SUGGESTIONS) {
    sections.push(`# ${pattern}`);
  }
  sections.push("");

  return sections.join("\n");
}

```

--------------------------------

### Language markdown format example

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/specs/2026-03-21-language-agnostic-design.md

Example structure for a language-specific markdown file, showing key concepts, import patterns, notable file patterns, and example summary style.

```markdown
# Python

## Key Concepts
- Decorators, comprehensions, generators, context managers, type hints, dunder methods

## Import Patterns
- `import module`, `from module import name`, relative imports

## Notable File Patterns
- `__init__.py` (package initializer), `conftest.py` (pytest), `pyproject.toml` (config)

## Example Summary Style
> "FastAPI route handler that accepts a Pydantic model, validates input..."
```

--------------------------------

### Install ignore package with pnpm

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-10-understandignore-impl.md

Run this command from the plugin root to add the `ignore` dependency to the core package. Uses pnpm's `--filter` flag to target `@understand-anything/core`.

```bash
cd understand-anything-plugin && pnpm add --filter @understand-anything/core ignore
```

--------------------------------

### Failing tests for buildOnboardingGuide

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase4-implementation.md

Test suite for the buildOnboardingGuide function. It verifies that the generated guide contains expected sections and content, and handles graphs with no layers or tour gracefully.

```typescript
// packages/skill/src/__tests__/onboard-builder.test.ts
import { describe, it, expect } from "vitest";
import { buildOnboardingGuide } from "../onboard-builder.js";
import type { KnowledgeGraph } from "@understand-anything/core";

const sampleGraph: KnowledgeGraph = {
  version: "1.0.0",
  project: {
    name: "test-project",
    languages: ["typescript", "python"],
    frameworks: ["express", "prisma"],
    description: "A test REST API",
    analyzedAt: "2026-03-14T00:00:00Z",
    gitCommitHash: "abc123",
  },
  nodes: [
    { id: "file:src/index.ts", type: "file", name: "index.ts", filePath: "src/index.ts", summary: "Entry point", tags: ["entry"], complexity: "simple" },
    { id: "file:src/service.ts", type: "file", name: "service.ts", filePath: "src/service.ts", summary: "Core service", tags: ["service"], complexity: "complex" },
    { id: "concept:auth", type: "concept", name: "Auth Flow", summary: "JWT-based authentication", tags: ["concept", "auth"], complexity: "complex" },
  ],
  edges: [
    { source: "file:src/index.ts", target: "file:src/service.ts", type: "imports", direction: "forward", weight: 0.8 },
  ],
  layers: [
    { id: "layer:api", name: "API Layer", description: "Routes and handlers", nodeIds: ["file:src/index.ts"] },
    { id: "layer:service", name: "Service Layer", description: "Business logic", nodeIds: ["file:src/service.ts"] },
  ],
  tour: [
    { order: 1, title: "Start Here", description: "Begin with index.ts", nodeIds: ["file:src/index.ts"] },
    { order: 2, title: "Core Logic", description: "Service layer", nodeIds: ["file:src/service.ts"] },
  ],
};

describe("onboard-builder", () => {
  it("includes project overview section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("# test-project");
    expect(guide).toContain("A test REST API");
  });

  it("lists languages and frameworks", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("typescript");
    expect(guide).toContain("express");
  });

  it("includes architecture layers section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Architecture");
    expect(guide).toContain("API Layer");
    expect(guide).toContain("Service Layer");
  });

  it("includes key concepts section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Key Concepts");
    expect(guide).toContain("Auth Flow");
  });

  it("includes getting started / tour section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Getting Started");
    expect(guide).toContain("Start Here");
  });

  it("includes complexity hotspots", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## Complexity Hotspots");
    expect(guide).toContain("service.ts");
  });

  it("includes file map section", () => {
    const guide = buildOnboardingGuide(sampleGraph);
    expect(guide).toContain("## File Map");
  });

  it("handles graph with no layers gracefully", () => {
    const noLayers = { ...sampleGraph, layers: [] };
    const guide = buildOnboardingGuide(noLayers);
    expect(guide).toContain("# test-project");
  });

  it("handles graph with no tour gracefully", () => {
    const noTour = { ...sampleGraph, tour: [] };
    const guide = buildOnboardingGuide(noTour);
    expect(guide).toContain("# test-project");
  });
});
```

--------------------------------

### Install fuse.js in core package

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Installs the fuse.js dependency in the core package using pnpm.

```bash
cd packages/core && pnpm add fuse.js
```

--------------------------------

### Build and verify core package

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-21-language-agnostic-plan.md

Runs the build for the @understand-anything/core package. Expected to succeed with no errors.

```bash
cd understand-anything-plugin && pnpm --filter @understand-anything/core build
```

--------------------------------

### Install zod in core package

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase2-implementation.md

Command to install zod in the core package using pnpm.

```bash
cd packages/core && pnpm add zod
```

--------------------------------

### Test, Lint, and Build

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Run all tests, lint, and build packages to verify changes.

```bash
# Run all tests
pnpm --filter @understand-anything/core test
pnpm test

# Run linter
pnpm lint

# Build packages
pnpm build
```

--------------------------------

### Install new dependencies with pnpm

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-28-understand-anything-extension-impl.md

Command to install yaml, @iarna/toml, and jsonc-parser in the core package directory.

```bash
cd understand-anything-plugin/packages/core
pnpm add yaml @iarna/toml jsonc-parser
```

--------------------------------

### Fork and Clone Repository

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Clone the repository from your fork and navigate into the project directory.

```bash
git clone https://github.com/YOUR_USERNAME/Understand-Anything.git
cd Understand-Anything
```

--------------------------------

### Install dashboard dependencies

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase1-implementation.md

Installs runtime dependencies (@xyflow/react, @monaco-editor/react, zustand) and dev dependencies (tailwindcss, @tailwindcss/vite) for the dashboard package.

```bash
cd packages/dashboard && pnpm add @xyflow/react @monaco-editor/react zustand && pnpm add -D tailwindcss @tailwindcss/vite
```

--------------------------------

### Build Core Package

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Build the @understand-anything/core package.

```bash
pnpm --filter @understand-anything/core build
```

--------------------------------

### Create skill directory

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-01-business-domain-knowledge-impl.md

Creates the directory for the /understand-domain skill.

```bash
mkdir -p understand-anything-plugin/skills/understand-domain
```

--------------------------------

### Fast path: run prebuilt viewer with npx

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md

Runs the self-contained viewer tarball pinned to the installed plugin version. Requires PLUGIN_ROOT and PROJECT_DIR to be set (steps 1 and 3). Prints the same dashboard URL line as the dev server; if it appears, skip steps 5-6.

```bash
: "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"
: "${PROJECT_DIR:?Run step 1 first so PROJECT_DIR is set}"
PLUGIN_VERSION=$(node -p "require('$PLUGIN_ROOT/package.json').version")
VIEWER_URL="https://github.com/Egonex-AI/Understand-Anything/releases/download/v${PLUGIN_VERSION}/understand-anything-viewer.tgz"
npx --yes "$VIEWER_URL" "$PROJECT_DIR"
```

```text
🔑  Dashboard URL: http://127.0.0.1:<PORT>?token=<TOKEN>
```

--------------------------------

### Fallback: build core package

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand-dashboard/SKILL.md

Builds the @understand-anything/core package, which the dashboard depends on. Requires PLUGIN_ROOT to be set.

```bash
: "${PLUGIN_ROOT:?Run step 3 first so PLUGIN_ROOT is set}"
cd "$PLUGIN_ROOT" && pnpm --filter @understand-anything/core build
```

--------------------------------

### Find installed plugin version

Source: https://github.com/egonex-ai/understand-anything/blob/main/CLAUDE.md

Lists the installed versions in the Claude Code plugin cache. The version must match what the marketplace currently serves.

```bash
ls ~/.claude/plugins/cache/understand-anything/understand-anything/
```

--------------------------------

### Run Tests

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Run tests for the core package and the entire project.

```bash
pnpm --filter @understand-anything/core test
pnpm test
```

--------------------------------

### Inter-group import frequency matrix output example

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/agents/architecture-analyzer.md

Example output matrix for inter-group import frequency, showing counts of import edges between directory groups.

```text
routes -> services: 12
routes -> utils: 3
services -> models: 8
services -> utils: 5
```

--------------------------------

### Cross-category dependency matrix output example

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/agents/architecture-analyzer.md

Example output matrix for cross-category dependency analysis, showing counts of edges between node type groups with edge types.

```text
config -> file: 5 (configures)
document -> file: 3 (documents)
service -> file: 2 (deploys)
pipeline -> file: 1 (triggers)
schema -> file: 2 (defines_schema)
```

--------------------------------

### Build dashboard package

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase3-implementation.md

Command to verify the dashboard compiles and renders after implementing the LearnPanel component.

```bash
cd packages/dashboard && pnpm build
```

--------------------------------

### Go test code for extractor

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-15-language-extractors-impl.md

Representative Go code for testing the Go extractor. Includes imports, a struct with fields, a method, and a function. Expected extraction: 2 functions (Start, NewServer), 1 class/struct (Server with method Start, properties Host/Port), 2 imports, exports (Server, Start, NewServer — all capitalized), and a call graph (Start→fmt.Println).

```go
package main

import (
    "fmt"
    "os"
)

type Server struct {
    Host string
    Port int
}

func (s *Server) Start() error {
    fmt.Println("starting")
    return nil
}

func NewServer(host string, port int) *Server {
    return &Server{Host: host, Port: port}
}
```

--------------------------------

### Build and run dashboard for manual smoke test

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-05-03-graph-layout-scaling.md

Run these commands to build the dashboard package and start the dev server. Then open a graph with domain data and switch to the Domain view to verify nodes render, edges are visible, and no console errors appear.

```bash
pnpm --filter @understand-anything/dashboard build
pnpm dev:dashboard
```

--------------------------------

### Vitest test structure example

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Use this structure when writing tests with Vitest. Place tests in __tests__ directories or *.test.ts files. The example shows the arrange-act-assert pattern with imports from 'vitest'.

```typescript
import { describe, it, expect } from 'vitest';

describe('MyFeature', () => {
  it('should do something', () => {
    // Arrange
    const input = 'test';

    // Act
    const result = myFunction(input);

    // Assert
    expect(result).toBe('expected');
  });
});
```

--------------------------------

### Keep learning with various commands

Source: https://github.com/egonex-ai/understand-anything/blob/main/README.md

Commands for asking questions, analyzing changes, explaining specific files, generating onboarding guides, extracting domain knowledge, analyzing wiki knowledge bases, re-running analysis, auto-updating on commits, and scoping to subdirectories.

```bash
# Ask anything about the codebase
/understand-chat How does the payment flow work?

# Analyze impact of your current changes
/understand-diff

# Deep-dive into a specific file or function
/understand-explain src/auth/login.ts

# Generate an onboarding guide for new team members
/understand-onboard

# Extract business domain knowledge (domains, flows, steps)
/understand-domain

# Analyze a Karpathy-pattern LLM wiki knowledge base
/understand-knowledge ~/path/to/wiki

# Re-run anytime — incremental by default (only re-analyzes changed files)
/understand

# Auto-update on every commit via a post-commit hook
/understand --auto-update

# Scope to a subdirectory (for huge monorepos)
/understand src/frontend
```

--------------------------------

### Language Link Example in README

Source: https://github.com/egonex-ai/understand-anything/blob/main/CONTRIBUTING.md

Shows how to add a language link in the main README.md when adding a new language translation. The example uses HTML anchor tags with the language code in the filename.

```markdown
<a href="README.md">English</a> | <a href="README.fr-FR.md">Français</a>
```

--------------------------------

### Build and run full test suite

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-14-phase3-implementation.md

Command to build the core package and run the full test suite.

```bash
cd packages/core && pnpm build && pnpm test
```

--------------------------------

### Run tests and build for @understand-anything/core

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-04-10-understandignore-impl.md

Runs the test suite for the ignore-generator test file and then builds the core package. Expected outcomes are all tests passing and a clean build.

```bash
pnpm --filter @understand-anything/core test -- --run src/__tests__/ignore-generator.test.ts
```

```bash
pnpm --filter @understand-anything/core build
```

--------------------------------

### Update scanner script output format example

Source: https://github.com/egonex-ai/understand-anything/blob/main/docs/superpowers/plans/2026-03-27-token-reduction-impl.md

JSON example to update the 'Script Output Format' section to include the importMap field. Shows the expected structure with importMap mapping file paths to resolved imports.

```json
{
  "scriptCompleted": true,
  "name": "project-name",
  "rawDescription": "...",
  "readmeHead": "...",
  "languages": ["javascript", "typescript"],
  "frameworks": ["React", "Vite"],
  "files": [
    {"path": "src/index.ts", "language": "typescript", "sizeLines": 150}
  ],
  "totalFiles": 42,
  "estimatedComplexity": "moderate",
  "importMap": {
    "src/index.ts": ["src/utils.ts", "src/config.ts"],
    "src/utils.ts": []
  }
}
```

--------------------------------

### Get current git commit hash

Source: https://github.com/egonex-ai/understand-anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md

Retrieves the current commit hash of the repository using git.

```bash
git rev-parse HEAD
```
Tokens:
Raw