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

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.

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.

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:

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

2. Build the core analysis engine:

pnpm --filter @understand-anything/core build

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

pnpm --filter @understand-anything/core test

4. Build the Claude Code plugin package:

pnpm --filter @understand-anything/skill build

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

pnpm test

6. Build and launch the dashboard locally:

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

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

node scripts/generate-large-graph.mjs 3000

All commands above are exposed as scripts in the root package.json.

Contribution Workflow and Submission Guidelines

The repository enforces a structured workflow to keep the monorepo stable. Always consult 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:

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 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 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:

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 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:

// 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. Update the theme object and rebuild:

// 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 — Skill prompt that drives LLM behavior during analysis.
• 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 — Continuous integration workflow that validates every pull request.
• CONTRIBUTING.md — Detailed contribution guidelines and code-style rules.
• CLAUDE.md — Architecture decisions, cross-platform gotchas, and versioning instructions.
• 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:

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}