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

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 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, 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 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, 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 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, 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, 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, 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, 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, performs the final pipeline stage. It sanity-checks the accumulated graph data, deduplicates edges, validates consistency, and produces the canonical knowledge-graph.json file that the dashboard loads and visualizes.

How the Pipeline Orchestrates Agent Execution

The /understand skill in 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 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.

Phase 4 – TOUR: The Tour-Builder consumes the nodes, edges, and architectural layers to compute entry points and generate tour.json.

Phase 5 – REVIEW: Finally, the Graph-Reviewer cleans the graph, removes duplicates, and writes the final 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:

# 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 and 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 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 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, 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, which the orchestrator reads to extract $FILE_LIST for batching. Similarly, the Architecture-Analyzer writes 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.

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