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

> Discover how Understand Anything builds knowledge graphs from code repositories using a multi-agent pipeline and a core orchestration engine. Learn about deterministic JSON artifacts and queryable graph structures.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: internals
- Published: 2026-06-24

---

**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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/.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:

```bash

# 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:

```text
.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`:

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

```

Launch the interactive dashboard to visualize the results:

```bash
pnpm dev:dashboard

```

The dashboard fetches [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/analyzer/graph-builder.ts) orchestrates the synchronous pipeline and produces the final [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json) or [`layers.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.