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

The multi-agent pipeline in Lum1104/Understand-Anything uses a deterministic, file-based orchestration strategy where the /understand skill in 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) Detects every file in the repository, identifies languages and frameworks, calculates line counts, and builds a complete importMap. It outputs scan-result.json containing the project name, description, languages, frameworks, file list, import map, and complexity metrics.

File-Analyzer (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) 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, assigning each file to a single architectural layer based on directory groupings and import density analysis.

Tour-Builder (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 with titles, descriptions, and referenced node IDs.

Graph-Reviewer (agents/graph-reviewer.md) Performs final sanity checks, deduplicates edges, and validates consistency before writing the canonical 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, 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 to .understand-anything/intermediate/, providing the foundation for subsequent operations.

Phase 2: Parallel Analysis SKILL.md reads 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.

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.

Phase 5: Finalization The Graph-Reviewer performs the final pass, cleaning entity duplicates, validating edge consistency, and serializing the definitive 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 orchestrator passes state between phases by:

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

# 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 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 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 and 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, 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, which SKILL.md reads to populate $FILE_LIST for File-Analyzer batches. Similarly, Architecture-Analyzer consumes the accumulated graph nodes to produce 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), the underlying skill definitions and agent prompts reside in standard markdown files (SKILL.md and agents/*.md). The core logic in understand-anything-plugin/src/ including understand-chat.ts and context-builder.ts could theoretically be adapted for standalone execution, though the current implementation expects the Claude Code runtime environment for sub-agent dispatch.

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