# How the Multi-Agent Pipeline Orchestrates 5 Specialized Agents in Understand-Anything

> Discover how the Understand Anything multi-agent pipeline orchestrates 5 specialized agents using a file-based strategy and JSON intermediates to analyze your codebase.

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

---

**The multi-agent pipeline in Lum1104/Understand-Anything uses a deterministic, file-based orchestration strategy where the `/understand` skill in [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) sequentially dispatches five specialized sub-agents—Project-Scanner, File-Analyzer, Architecture-Analyzer, Tour-Builder, and Graph-Reviewer—processing codebases through JSON intermediates stored in `.understand-anything/intermediate/`.**

This repository implements a fully automated system that transforms raw code into interactive knowledge graphs and guided tours. The **multi-agent pipeline** operates through tight coordination between deterministic extraction scripts and LLM-driven semantic analysis. Understanding this orchestration reveals how the tool achieves consistent, scalable codebase comprehension without ad-hoc prompt chains.

## The Five-Agent Architecture

The pipeline consists of five tightly-coupled agents, each defined in dedicated markdown files under `understand-anything-plugin/agents/`:

**Project-Scanner** ([`agents/project-scanner.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/project-scanner.md))
Detects every file in the repository, identifies languages and frameworks, calculates line counts, and builds a complete `importMap`. It outputs [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json) containing the project name, description, languages, frameworks, file list, import map, and complexity metrics.

**File-Analyzer** ([`agents/file-analyzer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/file-analyzer.md))
Processes code in batches of approximately 20–30 files using a deterministic tree-sitter extraction script (`extract-structure.mjs`). It generates semantic nodes and edges for functions, classes, and call relationships, outputting one JSON per batch that later merges into the global knowledge graph.

**Architecture-Analyzer** ([`agents/architecture-analyzer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/architecture-analyzer.md))
Consumes the complete knowledge graph (nodes plus import edges) to discover logical architectural layers such as API, Service, Data, and UI. It produces [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json), assigning each file to a single architectural layer based on directory groupings and import density analysis.

**Tour-Builder** ([`agents/tour-builder.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/tour-builder.md))
Generates a pedagogical tour of 5–15 steps that guides newcomers through critical entry points and dependency chains. It computes entry-point scores, fan-in/out rankings, and tight-coupling clusters to produce an ordered [`tour.json`](https://github.com/Lum1104/Understand-Anything/blob/main/tour.json) with titles, descriptions, and referenced node IDs.

**Graph-Reviewer** ([`agents/graph-reviewer.md`](https://github.com/Lum1104/Understand-Anything/blob/main/agents/graph-reviewer.md))
Performs final sanity checks, deduplicates edges, and validates consistency before writing the canonical [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) consumed by the dashboard UI.

## Pipeline Orchestration Flow

The orchestration begins when a user invokes the `/understand` skill via Claude Code, CLI, or dashboard interaction. In [`understand-anything-plugin/skills/understand/SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-anything-plugin/skills/understand/SKILL.md), the `buildChatPrompt` function constructs a chat prompt that executes the pipeline in distinct phases.

**Phase 1: Discovery**
The skill first dispatches the **Project-Scanner** as a sub-agent. The scanner writes [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json) to `.understand-anything/intermediate/`, providing the foundation for subsequent operations.

**Phase 2: Parallel Analysis**
[`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) reads [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json) and extracts `$FILE_LIST` and `$IMPORT_MAP` into environment variables. It batches the file list into groups of approximately 25 files, then dispatches **File-Analyzer** sub-agents in parallel (up to 5 concurrent batches). Each analyzer processes its assigned batch using the deterministic extraction script before returning structural data.

**Phase 3: Layer Assignment**
After batch completion, the accumulated node and edge data forms a raw knowledge graph. The **Architecture-Analyzer** ingests this graph, computes import topology metrics, and assigns each node to logical architectural layers, persisting the results as [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json).

**Phase 4: Tour Generation**
The **Tour-Builder** consumes the nodes, edges, and layer assignments to calculate optimal learning paths. It weighs entry-point significance and dependency complexity to generate the sequential [`tour.json`](https://github.com/Lum1104/Understand-Anything/blob/main/tour.json).

**Phase 5: Finalization**
The **Graph-Reviewer** performs the final pass, cleaning entity duplicates, validating edge consistency, and serializing the definitive [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) that powers the interactive visualization.

## Inter-Agent Communication Protocol

Communication between agents relies strictly on **JSON files** and **environment variables**, never through ad-hoc LLM prompt content. This design ensures determinism and reproducibility across runs.

Intermediate artifacts reside exclusively in `.understand-anything/intermediate/`. The [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) orchestrator passes state between phases by:
- Reading [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json) to extract `$FILE_LIST` for batching
- Setting environment variables that point to batch-specific JSON outputs
- Aggregating individual batch results from File-Analyzer into a unified graph structure before passing to Architecture-Analyzer

The only non-deterministic components involve LLM-driven semantic enrichment (such as function summarization), which operate atop the deterministic tree-sitter extraction results rather than replacing them.

## Running the Multi-Agent Pipeline

Execute the full pipeline from the repository root using Node.js ≥ 22 and pnpm ≥ 10:

```bash

# Install dependencies and build the project

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

# Trigger the multi-agent pipeline

claude-code run /understand --full

```

Alternatively, initiate the process through the dashboard by clicking "Run /understand". The command launches the skill, which sequentially orchestrates all five agents. 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 renders the interactive graph from [`knowledge-graph.json`](https://github.com/Lum1104/Understand-Anything/blob/main/knowledge-graph.json) and displays the tour sidebar generated by the Tour-Builder.

## Summary

- The **multi-agent pipeline** consists of five specialized agents: Project-Scanner, File-Analyzer, Architecture-Analyzer, Tour-Builder, and Graph-Reviewer.
- Orchestration occurs through **[`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md)** in `understand-anything-plugin/skills/understand/`, which manages the execution flow via `buildChatPrompt`.
- **File-Analyzer** processes code in batches of ~25 files with up to 5 concurrent workers, using the deterministic `extract-structure.mjs` script.
- Inter-agent communication uses **JSON intermediates** stored in `.understand-anything/intermediate/` and environment variables like `$FILE_LIST` and `$IMPORT_MAP`.
- The pipeline outputs [`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) to power the interactive dashboard and guided codebase exploration.

## Frequently Asked Questions

### How does the multi-agent pipeline handle large codebases without hitting token limits?

The pipeline implements **batch processing** where the File-Analyzer receives approximately 20–30 files per invocation (roughly 25 files per batch), with up to 5 concurrent workers processing separate batches simultaneously. This chunking strategy, defined in [`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md), ensures each sub-agent receives only relevant context while maintaining parallel execution efficiency.

### What makes the pipeline deterministic despite using LLM agents?

Only the **semantic enrichment steps** (such as generating human-readable descriptions for functions) involve non-deterministic LLM outputs. All structural extraction relies on the deterministic `extract-structure.mjs` tree-sitter script. Agent coordination occurs through fixed JSON schemas and environment variables rather than free-form text, ensuring reproducible knowledge graph construction across multiple runs.

### How do the agents pass data without direct function calls?

Agents communicate through **shared JSON artifacts** in `.understand-anything/intermediate/`. For example, Project-Scanner writes [`scan-result.json`](https://github.com/Lum1104/Understand-Anything/blob/main/scan-result.json), which SKILL.md reads to populate `$FILE_LIST` for File-Analyzer batches. Similarly, Architecture-Analyzer consumes the accumulated graph nodes to produce [`layers.json`](https://github.com/Lum1104/Understand-Anything/blob/main/layers.json), which Tour-Builder reads to compute entry points. This file-based protocol decouples the agents while maintaining strict data contracts.

### Can the pipeline run outside of Claude Code?

While designed for Claude Code integration (via [`src/index.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/src/index.ts)), the underlying skill definitions and agent prompts reside in standard markdown files ([`SKILL.md`](https://github.com/Lum1104/Understand-Anything/blob/main/SKILL.md) and `agents/*.md`). The core logic in `understand-anything-plugin/src/` including [`understand-chat.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/understand-chat.ts) and [`context-builder.ts`](https://github.com/Lum1104/Understand-Anything/blob/main/context-builder.ts) could theoretically be adapted for standalone execution, though the current implementation expects the Claude Code runtime environment for sub-agent dispatch.