# How the Multi-Agent Pipeline Works in Understand-Anything: A 5-Step Technical Breakdown

> Understand the multi-agent pipeline in Lum1104/Understand-Anything. Explore 5 steps transforming code into interactive knowledge graphs with specialized agents for deterministic extraction and LLM enrichment.

- Repository: [Yuxiang Lin/Understand-Anything](https://github.com/Lum1104/Understand-Anything)
- Tags: deep-dive
- Published: 2026-05-22

---

**The multi-agent pipeline in Lum1104/Understand-Anything orchestrates five specialized agents—Project-Scanner, File-Analyzer, Architecture-Analyzer, Tour-Builder, and Graph-Reviewer—to transform raw codebases into interactive knowledge graphs through deterministic extraction and LLM-powered semantic enrichment.**

Understand-Anything implements a fully automated multi-agent pipeline that converts code repositories into interactive knowledge graphs and guided tours. The pipeline is orchestrated by the `/understand` skill defined in [`skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/SKILL.md) and executes five tightly-coupled agents sequentially. This architecture ensures deterministic code analysis while leveraging LLM capabilities for semantic understanding.

## The Five Agents in the Multi-Agent Pipeline

The multi-agent pipeline consists of five distinct agents, each responsible for a specific transformation stage. All intermediate artifacts live under `.understand-anything/intermediate/` and are passed between agents via environment variables and JSON files.

### 1. Project-Scanner (Discovery Phase)

The **Project-Scanner** agent, defined in [`agents/project-scanner.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/project-scanner.md), performs the initial filesystem discovery. It detects every file, identifies programming languages and frameworks, calculates line counts, and builds an `importMap` for dependency tracking.

The agent outputs [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json) containing the project name, description, detected languages, frameworks, complete file list, import map, and complexity metrics. This file serves as the foundation for all subsequent pipeline stages.

### 2. File-Analyzer (Structural Extraction)

The **File-Analyzer** agent, documented in [`agents/file-analyzer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/file-analyzer.md), processes the codebase in batches of approximately 20–30 files per batch. It executes a deterministic tree-sitter extraction script (`extract-structure.mjs`) to identify functions, classes, calls, and other semantic structures.

Each batch produces a separate JSON file containing nodes and edges, which are later merged into the global knowledge graph. The [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) orchestrator dispatches up to five File-Analyzer sub-agents concurrently to maximize throughput.

### 3. Architecture-Analyzer (Layer Detection)

The **Architecture-Analyzer** agent, located in [`agents/architecture-analyzer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/architecture-analyzer.md), consumes the complete knowledge graph including all nodes and import edges. It computes directory groupings, analyzes import densities, and assigns each file to a logical architectural layer such as API, Service, Data, or UI.

This agent outputs [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json), which maps every node to a single architectural layer, enabling the visualization of high-level system structure.

### 4. Tour-Builder (Pedagogical Guidance)

The **Tour-Builder** agent, defined in [`agents/tour-builder.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/tour-builder.md), generates a pedagogical guided tour consisting of 5–15 steps. It analyzes entry-point scores, fan-in/out rankings, and tight-coupling clusters to determine the most important codebase entry points for newcomers.

The agent outputs [`tour.json`](https://github.com/Lum1104/Understand-Anything/blob/main/tour.json), an ordered sequence of steps with titles, descriptions, and referenced node IDs that the dashboard renders as an interactive onboarding experience.

### 5. Graph-Reviewer (Final Validation)

The **Graph-Reviewer** agent, documented in [`agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/graph-reviewer.md), performs the final pipeline stage. It sanity-checks the accumulated graph data, deduplicates edges, validates consistency, and produces the canonical [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) file that the dashboard loads and visualizes.

## How the Pipeline Orchestrates Agent Execution

The `/understand` skill in [`skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/skills/understand/SKILL.md) implements the orchestration logic through a `buildChatPrompt` function that manages agent dispatch and data flow.

**Phase 1 – SCAN**: The orchestrator first invokes the Project-Scanner as a sub-agent, which writes [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json) to `.understand-anything/intermediate/`.

**Phase 2 – ANALYZE**: The orchestrator reads the scan results, extracts `$FILE_LIST` and `$IMPORT_MAP`, and batches the file list into chunks of approximately 25 files. For each batch, it dispatches a File-Analyzer sub-agent in parallel (maximum 5 concurrent executions).

**Phase 3 – ARCHITECTURE**: After all batches complete and the raw knowledge graph is assembled, the orchestrator invokes the Architecture-Analyzer to compute layers and output [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json).

**Phase 4 – TOUR**: The Tour-Builder consumes the nodes, edges, and architectural layers to compute entry points and generate [`tour.json`](https://github.com/Lum1104/Understand-Anything/blob/main/tour.json).

**Phase 5 – REVIEW**: Finally, the Graph-Reviewer cleans the graph, removes duplicates, and writes the final [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json).

Communication between agents never occurs through ad-hoc LLM prompts; instead, agents read from and write to specific JSON files in the intermediate directory, ensuring reproducible pipeline execution.

## Running the Multi-Agent Pipeline Locally

To execute the multi-agent pipeline on your own codebase, ensure you have Node.js ≥ 22 and pnpm ≥ 10 installed:

```bash

# From the repository root

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

# Trigger the complete pipeline

claude-code run /understand --full

```

The command launches the skill, which sequentially dispatches the five agents described above. Upon completion, the terminal displays a summary:

```

Project: my-app (Node.js web service)
Total files: 42 (code 35, config 5, docs 2)
Languages: javascript, typescript, yaml, markdown
Estimated complexity: moderate

```

The dashboard then loads [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) and [`tour.json`](https://github.com/Lum1104/Understand-Anything/blob/main/tour.json) from `.understand-anything/intermediate/` to render the interactive visualization and guided tour sidebar.

## Summary

- The **multi-agent pipeline** in Understand-Anything consists of five sequential agents: Project-Scanner, File-Analyzer, Architecture-Analyzer, Tour-Builder, and Graph-Reviewer.
- **Deterministic extraction** occurs via tree-sitter in the File-Analyzer, while LLM-powered semantic enrichment handles function summarization.
- **Inter-agent communication** uses JSON files in `.understand-anything/intermediate/` rather than prompt-based data passing.
- **Batching and concurrency** allow the File-Analyzer to process large codebases efficiently, handling approximately 25 files per batch with up to 5 concurrent sub-agents.
- The final output [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) serves as the single source of truth for the interactive dashboard visualization.

## Frequently Asked Questions

### What makes the Understand-Anything multi-agent pipeline deterministic?

The pipeline achieves determinism by using tree-sitter-based static analysis in the File-Analyzer rather than relying solely on LLM interpretation of code. While the LLM provides semantic enrichment (such as generating function summaries), it operates on the deterministic extraction results produced by the tree-sitter script `extract-structure.mjs`. Data passes between agents via structured JSON files rather than natural language, ensuring reproducible outputs across runs.

### How does the File-Analyzer handle large codebases efficiently?

The File-Analyzer implements a batching strategy where [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) divides the file list into chunks of approximately 20–30 files each. The orchestrator dispatches up to five File-Analyzer sub-agents concurrently, processing multiple batches in parallel. This approach prevents context window limitations and maximizes throughput while maintaining consistent JSON output format for later merging into the global knowledge graph.

### What is the role of the Architecture-Analyzer in the pipeline?

The Architecture-Analyzer processes the complete knowledge graph including all import edges to discover logical architectural layers. It analyzes directory groupings and import densities to classify files into categories such as API, Service, Data, or UI layers. The agent outputs [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json), which enables the dashboard to display high-level system architecture and helps the Tour-Builder identify appropriate entry points for different system components.

### How do agents communicate data between steps?

Agents communicate exclusively through JSON files stored in `.understand-anything/intermediate/`. For example, the Project-Scanner writes [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json), which the orchestrator reads to extract `$FILE_LIST` for batching. Similarly, the Architecture-Analyzer writes [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json) that the Tour-Builder consumes. This file-based communication ensures data integrity and allows for debugging by inspecting intermediate artifacts at each pipeline stage.