How Understand Anything's Multi-Agent Pipeline Works: From Code to Knowledge Graph

Understand Anything transforms raw code repositories into rich knowledge graphs by chaining five specialized agents that emit deterministic JSON artifacts, orchestrated by a core engine that stitches them into a queryable graph structure.

The open-source Understand Anything repository (Egonex-AI/Understand-Anything) automates codebase comprehension through a deterministic multi-agent pipeline. Rather than relying on monolithic analysis, the system decomposes the process into discrete, specialized agents that each handle a specific transformation step—from file scanning to graph validation. Each agent writes intermediate artifacts to .understand-anything/intermediate/, which the core engine merges into the final knowledge-graph.json that powers the dashboard, chat, and tour features.

The Five Specialized Agents

The pipeline processes your repository sequentially through five deterministic stages. Each agent consumes the output of the previous stage and produces structured JSON that feeds into the next.

Project Scanner

The Project Scanner performs the initial inventory pass. It enumerates every file in the repository, detects programming languages, assigns canonical fileCategory values, counts lines of code, and applies .understandignore filters. This agent produces ua-scan-files.json, containing the complete file list and statistics required by downstream analyzers.

File Analyzer

The File Analyzer runs the bundled extract-structure.mjs script (using tree-sitter and custom parsers) to extract functions, classes, imports, and non-code concepts. An LLM layer then enriches these structural elements with summaries, tags, and complexity scores. The agent builds function:, class:, and other typed nodes with structural edges, outputting ua-file-extract-results.json.

Architecture Analyzer

The Architecture Analyzer consumes the file list and import map to detect logical layers within your codebase. It groups files by directory and node type, computes intra-group and inter-group connection densities, and identifies deployment topology, data pipelines, and documentation coverage. From these signals, it assigns every node to exactly one logical layer (API, Service, Data, Infra, CI/CD, etc.), producing layers.json.

Tour Builder

The Tour Builder executes a graph-topology script that ranks nodes by fan-in and fan-out centrality. It selects entry-point candidates, walks the import graph using BFS, identifies tightly-coupled clusters, and assembles a guided learning tour consisting of 5-15 pedagogical steps. The output tour.json strings together code and non-code nodes in an optimal learning order.

Graph Reviewer

The Graph Reviewer performs deterministic validation against the graph schema. It verifies that every fileCategory node appears in a layer, that all edge IDs reference real nodes, that edge weights match the schema, and that the final JSON complies with structural requirements. If validation fails, it emits clear rejection messages; otherwise, it produces the final knowledge-graph.json.

How the Core Engine Orchestrates the Pipeline

The core engine coordinates agent execution through the GraphBuilder class located in packages/core/src/analyzer/graph-builder.ts. After each agent finishes, the engine reads the intermediate JSON from .understand-anything/intermediate/, merges the data into a single KnowledgeGraph object, and writes the consolidated output to .understand-anything/knowledge-graph.json.

This synchronous orchestration happens within a single /understand skill invocation, though the modular design allows individual agents to run independently for incremental rescans.

Pipeline Architecture and Design Principles

The multi-agent pipeline adheres to several strict architectural constraints that ensure reliability and consistency.

Determinism First

Steps 1-2 are fully deterministic scripts; the LLM only adds narrative elements such as summaries, tags, layer names, and tour prose. This separation ensures that structural analysis remains reproducible across runs.

Strict Node ID Prefixing

Every node uses a strict prefix system to guarantee predictable edge wiring:

• file: for source files
• function: for functions
• class: for classes
• config:, document:, service:, pipeline:, table:, endpoint:, schema:, resource: for specialized nodes

Layer-First Graph Construction

Logical layers are created before the tour generation phase. The tour references existing layers rather than creating them, ensuring the visualization can consistently color-code nodes by architectural layer.

Intermediate Artifact Resilience

Each agent writes to .understand-anything/intermediate/. The Graph Reviewer discards any stray or invalid files, making the pipeline resilient to partial failures and enabling debugging of specific transformation stages.

Running the Pipeline Locally

You can execute the full multi-agent pipeline on any repository using the following commands:

# Install dependencies

pnpm install

# Run the full analysis pipeline on the current repo

pnpm --filter @understand-anything/skill run understand --full

After execution, the following files appear in your repository:

.understand-anything/
├─ intermediate/
│  ├─ ua-scan-files.json          # Project Scanner output

│  ├─ ua-file-extract-results.json # File Analyzer output

│  ├─ layers.json                 # Architecture Analyzer output

│  ├─ tour.json                   # Tour Builder output

│  └─ knowledge-graph.json        # Final validated graph

Inspect the generated graph using jq:

jq '.' .understand-anything/intermediate/knowledge-graph.json | less

Launch the interactive dashboard to visualize the results:

pnpm dev:dashboard

The dashboard fetches knowledge-graph.json and renders the node-colored graph, layer sidebar, and interactive tour flow.

Summary

• Five specialized agents transform code into knowledge: Project Scanner, File Analyzer, Architecture Analyzer, Tour Builder, and Graph Reviewer.
• Deterministic processing ensures structural analysis is reproducible, while LLMs only handle narrative enrichment.
• Strict ID prefixes (file:, function:, class:, etc.) enable reliable edge wiring across the graph.
• Intermediate JSON artifacts in .understand-anything/intermediate/ allow debugging and incremental updates.
• GraphBuilder in packages/core/src/analyzer/graph-builder.ts orchestrates the synchronous pipeline and produces the final knowledge-graph.json.

Frequently Asked Questions

How does the pipeline handle partial failures?

The multi-agent pipeline writes intermediate artifacts to .understand-anything/intermediate/ after each stage. If a specific agent fails, the Graph Reviewer detects missing or invalid artifacts and emits clear rejection messages without corrupting the final graph. You can re-run individual agents without reprocessing the entire pipeline, making the system resilient to transient errors.

What is the difference between the File Analyzer and the Architecture Analyzer?

The File Analyzer (understand-anything-plugin/agents/file-analyzer.md) operates at the unit level, extracting functions, classes, and imports from individual files using tree-sitter parsers. The Architecture Analyzer (understand-anything-plugin/agents/architecture-analyzer.md) operates at the system level, consuming the file-level output to detect logical layers, deployment topology, and cross-module dependencies. The File Analyzer creates the nodes; the Architecture Analyzer organizes them into architectural layers.

Can I run individual agents separately from the full pipeline?

Yes. While the standard pnpm --filter @understand-anything/skill run understand --full command runs all five agents synchronously, the modular design in packages/core/src/analyzer/graph-builder.ts supports executing individual agents. This is useful for incremental rescans when only specific files change, allowing you to update ua-scan-files.json or layers.json without reprocessing the entire repository.

Where does the LLM processing occur in the pipeline?

LLM enrichment happens primarily in the File Analyzer (for summaries and tags) and Architecture Analyzer (for layer naming), while the Tour Builder uses LLM assistance for pedagogical prose. The Project Scanner and Graph Reviewer remain fully deterministic scripts. This design keeps the structural extraction reproducible while allowing natural language generation where context and explanation matter most.

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