# How the 7 Agents Collaborate in Understand Anything: A Complete Pipeline Guide

> Discover how 7 agents collaborate in Understand Anything to build a queryable knowledge graph from raw code. Learn about the complete pipeline and intermediate JSON artifacts.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Understand Anything uses seven specialized agents that run sequentially to transform a raw codebase into a queryable knowledge graph, with each agent writing intermediate JSON artifacts to a shared `.understand-anything/` directory.**

The **Understand Anything** project (Egonex-AI/Understand-Anything) implements a modular analysis engine where seven purpose-driven agents collaborate through a deterministic pipeline. This architecture breaks complex codebase comprehension into discrete, testable stages, allowing the system to incrementally build from raw file scanning to a final, validated knowledge graph consumed by the React dashboard.

## The Seven-Agent Pipeline Architecture

The collaboration model centers on **stateless, single-responsibility agents** orchestrated by a generic runner defined in the plugin’s [`index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/index.ts). Each agent adheres to a strict contract (`input-path → output-path`), reading from the shared `.understand-anything/` directory and writing structured JSON outputs for the next stage.

The seven agents execute in the following order:

1. **project-scanner** – Performs a shallow filesystem walk using `git ls-files` and tree-sitter parsing to build an `importMap` that maps every source file to its internal import relationships. Outputs [`scan-result.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/scan-result.json).

2. **file-analyzer** – Consumes the `importMap` to extract exported symbols (functions, classes, constants) and intra-project imports from each file’s AST, filtering out external packages. Outputs [`file-analysis.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/file-analysis.json).

3. **domain-analyzer** – Clusters symbols into logical domains (e.g., UI, data-layer, utils) by analyzing dense import neighborhoods and applying heuristics like common path prefixes. Outputs [`domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-graph.json).

4. **architecture-analyzer** – Elevates the domain graph into structural layers (UI, service, data) and calculates coupling metrics such as fan-in/out and cyclomatic complexity. Outputs [`architecture-summary.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/architecture-summary.json).

5. **article-analyzer** – Serializes the architecture summary into a human-readable markdown article describing the project’s structure. Outputs [`article.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/article.md).

6. **assemble-reviewer** – Merges all intermediate artifacts (file graph, domain graph, and architecture summary) into a unified [`review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/review.json) for dashboard consumption and incremental re-runs.

7. **graph-reviewer** – Validates the review against the schema defined in `packages/core/schema`, decorates nodes with UI-ready metadata (positions, colors, icons), and produces the canonical [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json).

## Step-by-Step Collaboration Flow

### Scanning and Import Mapping

The pipeline initiates with the **project-scanner**, which traverses the target repository and uses the **tree-sitter** parser to collect import statements. It generates [`scan-result.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/scan-result.json), a contract mapping each source file to the resolved internal paths it imports, establishing the foundation for all downstream analysis.

### Symbol Extraction and Graph Building

The **file-analyzer** reads [`scan-result.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/scan-result.json) and loads each file’s AST to extract granular symbol-level data. It records which symbols are referenced by each import edge, producing a fine-grained graph stored in [`file-analysis.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/file-analysis.json). This step specifically filters out external package dependencies to focus on internal code relationships.

### Domain Clustering and Architectural Modeling

The **domain-analyzer** consumes the symbol graph and applies clustering algorithms to identify logical domains based on import density and folder similarity. The subsequent **architecture-analyzer** then calculates inter-domain dependencies and generates a high-level architectural summary describing layer coupling and structural depth.

### Human-Readable Documentation Generation

The **article-analyzer** transforms the architectural JSON into [`article.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/article.md), which powers the dashboard’s “Info → Learn” pane. When users ask the system to “Explain the project,” this markdown file supplies the narrative description.

### Final Assembly and Validation

The **assemble-reviewer** combines all intermediate JSON artifacts into a single [`review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/review.json), enabling atomic unit tests and partial pipeline re-runs when only specific files change. Finally, the **graph-reviewer** validates this JSON against the core schema, enriches nodes with React-compatible metadata, and writes [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) for the dashboard to render.

## Shared State and the Agent Contract

All seven agents communicate through the **`.understand-anything/` directory**, making the pipeline stateless except for disk I/O. Each agent implements a standardized contract where it receives an input path, performs its transformation, and writes to a designated output path. This design allows individual steps to be parallelized (e.g., sharding file-analysis across CPU cores) while maintaining deterministic execution order.

If any agent fails, the runner aborts immediately and surfaces the specific agent error, simplifying debugging and ensuring partial results do not contaminate downstream stages.

## Orchestration and Execution

The **agent runner** located in the plugin’s [`index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/index.ts) handles invocation sequencing. While agents run sequentially by default, their lack of shared memory state (beyond the JSON files) enables parallel execution strategies for performance optimization in large codebases.

## Running the Full Pipeline Locally

Execute the complete seven-agent pipeline from the repository root using the following commands:

```bash

# Install workspace dependencies

pnpm install

# Compile core packages

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

# Trigger the full agent pipeline

understand --full

# Alternative: /understand --full

```

This sequence creates the `.understand-anything/` directory, runs all seven agents in order, and generates the final artifacts. Launch the dashboard with `pnpm dev:dashboard` to explore the interactive knowledge graph derived from [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json).

## Summary

- **Seven sequential agents** transform codebases through distinct stages: scanning, analysis, domain grouping, architecture modeling, documentation, assembly, and validation.
- **Shared JSON contracts** in `.understand-anything/` enable stateless, deterministic collaboration between agents.
- **Standardized I/O contracts** (`input-path → output-path`) allow the agent runner in [`index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/index.ts) to orchestrate the pipeline and support parallelization.
- **Tree-sitter parsing** and `git ls-files` drive the initial scanning phase, while the final **graph-reviewer** validates against `packages/core/schema` before producing [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json).

## Frequently Asked Questions

### What is the role of the project-scanner agent?

The **project-scanner** initiates the pipeline by walking the target repository, parsing every source file with tree-sitter, and building an `importMap` that documents file-to-file import relationships. It outputs [`scan-result.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/scan-result.json), which serves as the foundational data contract for all subsequent agents.

### How do the agents share data between stages?

Agents communicate exclusively through the **`.understand-anything/` directory**, where each agent writes JSON or markdown artifacts (e.g., [`file-analysis.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/file-analysis.json), [`domain-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-graph.json)) that the next agent reads as input. This disk-based shared state eliminates direct memory coupling and enables incremental pipeline re-runs.

### Can the pipeline run in parallel?

Yes, the agents are **stateless** apart from their file I/O, allowing stages like file-analysis to be sharded across CPU cores. However, the default orchestration in [`index.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/index.ts) runs them sequentially to ensure deterministic debugging; parallelization requires custom runner configuration.

### Where is the final knowledge graph consumed?

The **graph-reviewer** produces [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json), which the React dashboard consumes to render the interactive exploration interface. This final artifact includes UI-ready metadata such as node positions, colors, and icons, validated against the schema in `packages/core/schema`.