# How to Contribute to Lum1104/Understand-Anything Development: A Complete Guide

> Learn how to contribute to Lum1104/Understand-Anything development. Clone the monorepo, install dependencies, and submit pull requests that pass testing and build pipelines.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-07

---

**To contribute to Lum1104/Understand-Anything development, clone the pnpm monorepo, install dependencies with Node 22 and pnpm 10, and submit pull requests that pass the full Vitest, lint, and build pipeline.**

The **Understand Anything** project is an open-source tool that combines large-language-model reasoning with static analysis to generate interactive dashboards for exploring codebases. When you contribute to Lum1104/Understand-Anything development, you will work inside a pnpm monorepo with strict TypeScript settings, cross-platform WASM parsing, and a CI workflow defined in [`.github/workflows/ci.yml`](https://github.com/Lum1104/Understand-Anything/blob/main/.github/workflows/ci.yml).

## Repository Architecture and Technology Stack

The codebase is organized as a **pnpm monorepo** with three primary workspaces. Understanding this separation is essential before you modify any code.

### Core Analysis Engine

The **`@understand-anything/core`** workspace contains the shared analysis engine. Inside `understand-anything-plugin/packages/core/src/`, you will find type definitions, tree-sitter parsing via **web-tree-sitter** WASM, search utilities, schema logic, and tour generation. The core exports browser-safe sub-paths such as `./search`, `./types`, and `./schema` so that the dashboard can import them without pulling in Node-only modules.

### Dashboard Interface

The **`@understand-anything/dashboard`** workspace is a React and TypeScript web UI. It uses React Flow for graph rendering, Zustand for state management, and Tailwind CSS v4 for styling. The source lives in `understand-anything-plugin/packages/dashboard/src/`, and it renders a **graph-first** layout where 75 percent of the viewport is the graph and a 360 px sidebar shows document nodes.

### Claude Code Plugin

The **`understand-anything-plugin`** workspace houses the Claude Code plugin. It contains the **skills**, **agents**, and **hooks** that drive analysis pipelines. Agents are defined in `understand-anything-plugin/agents/`, intermediate results are written to `.understand-anything/intermediate/`, and the main skill entry point is [`understand-anything-plugin/src/understand-chat.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/understand-chat.ts).

## Local Setup to Contribute to Lum1104/Understand-Anything Development

Before you submit code, ensure your environment meets the minimum requirements: **Node.js >= 22** and **pnpm >= 10**.

1. Clone the repository and install dependencies:

```bash
git clone https://github.com/Lum1104/Understand-Anything.git
cd Understand-Anything
pnpm install

```

2. Build the core analysis engine:

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

```

3. Run the core test suite to verify the pipeline:

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

```

4. Build the Claude Code plugin package:

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

```

5. Run the full monorepo test suite, including skill tests:

```bash
pnpm test

```

6. Build and launch the dashboard locally:

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

```

7. Optionally, generate a large synthetic graph for performance testing:

```bash
node scripts/generate-large-graph.mjs 3000

```

All commands above are exposed as scripts in the root [`package.json`](https://github.com/Lum1104/Understand-Anything/blob/main/package.json).

## Contribution Workflow and Submission Guidelines

The repository enforces a structured workflow to keep the monorepo stable. Always consult [`CONTRIBUTING.md`](https://github.com/Lum1104/Understand-Anything/blob/main/CONTRIBUTING.md) for style guidelines, commit message formats, and naming conventions before you start coding.

### Reporting Issues and Proposing Features

Start by opening an issue using the templates in `.github/ISSUE_TEMPLATE/`. Describe the bug or feature request clearly so maintainers can triage it quickly.

### Forking, Branching, and Writing Code

Fork the repository, create a feature branch such as `feat/my-feature`, and write your changes in the appropriate workspace. Add new agents inside `understand-anything-plugin/agents/`, new skills inside `understand-anything-plugin/skills/`, and UI components inside `understand-anything-plugin/packages/dashboard/src/`.

### Testing and Linting Before Submission

Add **Vitest** unit tests under `understand-anything-plugin/packages/core/src/__tests__/` for new parsers or graph transformations. Run the local CI checks before opening a pull request:

```bash
pnpm lint
pnpm test

```

The root `eslint.config.mjs` defines the lint rules, and the project uses TypeScript strict mode.

### Pull Request Checks and CI

Push your branch to your fork and open a pull request. The [`.github/workflows/ci.yml`](https://github.com/Lum1104/Understand-Anything/blob/main/.github/workflows/ci.yml) workflow automatically runs lint, tests, and build checks. Address reviewer feedback promptly and ensure all status checks pass before merge. When bumping package versions, update all five version fields referenced in [`CLAUDE.md`](https://github.com/Lum1104/Understand-Anything/blob/main/CLAUDE.md) to keep the monorepo workspaces in sync.

## Common Development Tasks

New contributors often need to run scans, add agents, or adjust the dashboard. The following examples show the exact commands and file paths used in the Lum1104/Understand-Anything codebase.

### Running a Project Scan

To trigger a project scan, build the skill package and invoke the entry point:

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

# The entry point is located at:

# understand-anything-plugin/src/understand-chat.ts

```

The `project-scanner` agent reads the repository's [`README.md`](https://github.com/Lum1104/Understand-Anything/blob/main/README.md) and stores the first ten lines as `readmeHead`, which seeds the subsequent graph-building agents.

### Adding a New Agent to the Pipeline

Create an agent definition file such as [`understand-anything-plugin/agents/my-new-analyzer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/agents/my-new-analyzer.md):

```ts
// File: understand-anything-plugin/agents/my-new-analyzer.md
---
name: my-new-analyzer
description: An example agent that tags source files with custom metadata.
---
{
  "type": "agent",
  "steps": [
    {
      "name": "list-files",
      "action": "glob",
      "pattern": "**/*.ts"
    },
    {
      "name": "tag-files",
      "action": "write",
      "template": {
        "id": "file:${path}",
        "type": "source",
        "tags": ["my-tag"]
      }
    }
  ]
}

```

After saving the file, rebuild the skill package with `pnpm --filter @understand-anything/skill build` so the pipeline can discover the new agent.

### Rebuilding the Dashboard Theme

Dashboard styles are centralized in [`understand-anything-plugin/packages/dashboard/src/styles/theme.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/packages/dashboard/src/styles/theme.ts). Update the theme object and rebuild:

```ts
// File: understand-anything-plugin/packages/dashboard/src/styles/theme.ts
export const theme = {
  colors: {
    background: "#0a0a0a",
    accent: "#d4a574",
    secondary: "#a0c4ff"
  }
};

```

Run `pnpm --filter @understand-anything/dashboard build` to apply the changes.

## Critical Source Files and Directory Structure

When you contribute to Lum1104/Understand-Anything development, these files and directories define the project behavior:

- `understand-anything-plugin/packages/core/src/` — Core analysis engine with parsers, graph builder, and WASM tree-sitter integration.
- `understand-anything-plugin/packages/dashboard/src/` — React dashboard components and Tailwind theme configuration.
- `understand-anything-plugin/agents/` — Agent definitions, including the project-scanner and architecture-analyzer.
- [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md) — Skill prompt that drives LLM behavior during analysis.
- [`understand-anything-plugin/src/understand-chat.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/src/understand-chat.ts) — Main entry point for the Claude Code plugin skill.
- `scripts/generate-large-graph.mjs` — Script for generating synthetic performance-test graphs.
- [`.github/workflows/ci.yml`](https://github.com/Lum1104/Understand-Anything/blob/main/.github/workflows/ci.yml) — Continuous integration workflow that validates every pull request.
- [`CONTRIBUTING.md`](https://github.com/Lum1104/Understand-Anything/blob/main/CONTRIBUTING.md) — Detailed contribution guidelines and code-style rules.
- [`CLAUDE.md`](https://github.com/Lum1104/Understand-Anything/blob/main/CLAUDE.md) — Architecture decisions, cross-platform gotchas, and versioning instructions.
- [`package.json`](https://github.com/Lum1104/Understand-Anything/blob/main/package.json) — Root workspace definitions and pnpm script shortcuts.

## Summary

- Lum1104/Understand-Anything is a pnpm monorepo requiring Node 22 and pnpm 10.
- The three main workspaces are **`@understand-anything/core`**, **`@understand-anything/dashboard`**, and **`understand-anything-plugin`**.
- Always build the relevant workspace, add Vitest tests under `understand-anything-plugin/packages/core/src/__tests__/`, and run `pnpm lint` and `pnpm test` before submitting a pull request.
- New agents belong in `understand-anything-plugin/agents/` and must be rebuilt with `pnpm --filter @understand-anything/skill build` to become active.
- The dashboard imports only browser-safe sub-paths from the core to avoid runtime errors from Node-only APIs.

## Frequently Asked Questions

### What are the minimum system requirements to contribute to Lum1104/Understand-Anything development?

You need **Node.js 22 or higher** and **pnpm 10 or higher**. These versions are required because the build scripts and workspace filters rely on modern Node APIs and pnpm monorepo features.

### How do I add a new analysis agent when I contribute to Lum1104/Understand-Anything development?

Create a Markdown agent definition in `understand-anything-plugin/agents/<agent-name>.md` with the proper frontmatter and JSON step definitions. After saving the file, run `pnpm --filter @understand-anything/skill build` to register the agent in the pipeline.

### Where should I write tests for new core graph transformations?

Place Vitest unit tests inside `understand-anything-plugin/packages/core/src/__tests__/`. Include tests for any new parser or graph transformation logic to ensure the analysis pipeline remains stable.

### How can I generate a large knowledge graph for dashboard performance testing?

Run the synthetic graph generator from the repository root:

```bash
node scripts/generate-large-graph.mjs 3000

```

The default node count is 3000. This produces a large graph that you can load into the dashboard to verify rendering and interaction performance.