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

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. 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.

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.

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.

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.

5. article-analyzer – Serializes the architecture summary into a human-readable markdown article describing the project’s structure. Outputs article.md.

6. assemble-reviewer – Merges all intermediate artifacts (file graph, domain graph, and architecture summary) into a unified 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.

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, 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 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. 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, 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, 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 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 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:

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

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 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.

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, 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, 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 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, 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.

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