# How the Egonex AI Multi-Agent System Orchestrates Scanning and Analysis

> Discover how the Egonex AI multi-agent system orchestrates scanning and analysis through a deterministic five-stage pipeline, transforming source trees into validated knowledge graphs.

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

---

**The Egonex AI multi-agent system executes a deterministic five-stage pipeline that transforms raw source trees into validated knowledge graphs through specialized agents handling project scanning, structural extraction, graph consolidation, architecture analysis, and LLM context generation.**

The Understand-Anything repository implements a modular orchestration architecture where deterministic agents process codebases sequentially. Each agent consumes structured JSON outputs from the previous stage, ensuring reproducible results while building a richly-typed knowledge graph suitable for LLM queries and interactive visualization.

## The Five-Agent Pipeline Architecture

The orchestration flow defined in `understand-anything-plugin/agents/` coordinates five specialized agents that convert source code into queryable knowledge representations.

### Project-Scanner Agent: Discovery and Inventory

The **Project-Scanner Agent** ([`agents/project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/project-scanner.md)) performs the initial codebase inventory by executing two bundled Node.js scripts against the raw source tree.

`scan-project.mjs` enumerates every file while applying `.understandignore` exclusion rules, detects programming languages, assigns canonical `fileCategory` classifications, and calculates complexity metrics including line counts. Simultaneously, `extract-import-map.mjs` parses each file using **tree-sitter** to generate [`ua-import-map-output.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-import-map-output.json), recording every internal import edge.

This stage produces two critical artifacts: [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json) containing the canonical file list, and [`ua-import-map-output.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-import-map-output.json) mapping all import relationships.

### File-Analyzer Agent: Structural Extraction

The **File-Analyzer Agent** ([`agents/file-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/file-analyzer.md)) consumes the file list from the Project-Scanner and operates in two phases. Phase 1 runs `extract-structure.mjs` on batched file subsets, using tree-sitter to extract functions, classes, exports, and metrics like line counts and import counts.

Phase 2 maps these raw extractions to the knowledge-graph schema defined in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts). The agent creates nodes for every file (types: `file`, `config`, `document`, `service`) and for significant functions or classes exceeding 10 lines or marked as exported. It emits edges such as `contains`, `imports`, `calls`, and `configures` exactly as specified in the agent documentation, outputting fragmented `batch-<n>.json` files.

### Graph-Reviewer Agent: Graph Consolidation

The **Graph-Reviewer Agent** ([`agents/graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/graph-reviewer.md)) merges per-batch JSON fragments from the File-Analyzer into a single coherent graph stored in `.understand-anything/intermediate/`. This agent validates node-ID uniqueness across all batches, verifies that every edge's source and target nodes exist, and applies the final layer-assignment step ensuring each file belongs to exactly one architectural layer.

The output is a validated [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) ready for architectural analysis.

### Architecture-Analyzer Agent: Layer Detection

The **Architecture-Analyzer Agent** ([`agents/architecture-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/agents/architecture-analyzer.md)) runs the deterministic Node.js script [`ua-arch-analyze.js`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-arch-analyze.js) against the complete merged graph. It generates structural summaries including directory groups, node-type distributions, import adjacency matrices, and cross-category edge counts.

This agent produces candidate layer assignments (`layer:api`, `layer:service`, `layer:infrastructure`) and constructs a `deploymentTopology`, `dataPipeline`, and `docCoverage` analysis, outputting [`layers.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layers.json) with density metrics and dependency directions derived from the import graph.

### Core Orchestration: Context Generation

The **Core Orchestration Glue** connects the knowledge graph to LLM interfaces through [`src/context-builder.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/context-builder.ts) and [`src/understand-chat.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/understand-chat.ts). The `buildChatContext` function loads the assembled graph, optionally filters nodes by user query, and produces a compact text representation. The `buildChatPrompt` function injects this context into a system prompt for Claude or ChatGPT, ensuring the context remains ordered, truncated to token limits, and includes layer information when available.

## Deterministic Execution Guarantees

Each agent in the Egonex AI pipeline provides specific integrity guarantees:

- **Project-Scanner**: Produces deterministic file lists with no invented paths, accurate language detection, and complete import maps
- **File-Analyzer**: Emits every file as a node and all imports as edges exactly as listed in `batchImportData`
- **Graph-Reviewer**: Ensures node-ID uniqueness and edge validity before passing to downstream consumers
- **Architecture-Analyzer**: Assigns exactly one layer per file with density metrics computed from the import graph

## Running the Pipeline

Execute the complete orchestration from the repository root using the npm scripts defined in [`package.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/package.json):

```bash

# Build required core and skill packages

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

# Run the full agent pipeline

pnpm run understand --full

```

This command internally triggers the sequential execution: project-scanner → file-analyzer → graph-reviewer → architecture-analyzer.

Inspect the generated graph structure:

```bash

# Count total nodes in the knowledge graph

cat .understand-anything/intermediate/knowledge-graph.json | jq '.nodes | length'

```

Launch the interactive dashboard to visualize results:

```bash
pnpm --filter @understand-anything/dashboard dev

```

The dashboard loads the graph from [`/.understand-anything/file-content.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//.understand-anything/file-content.json) and renders force-directed layouts showing layers and import relationships.

## Programmatic Integration

Consume the pipeline output programmatically using the context builder functions:

```typescript
import { buildChatPrompt } from "./understand-anything-plugin/src/understand-chat.js";
import type { KnowledgeGraph } from "@understand-anything/core";

// Load the assembled graph after agents complete
import graph from "../.understand-anything/intermediate/knowledge-graph.json" assert { type: "json" };

const userQuestion = "How does the authentication flow work?";
const prompt = buildChatPrompt(graph as KnowledgeGraph, userQuestion);

// Send prompt to your LLM endpoint
console.log(prompt);

```

## Dashboard Visualization

The React dashboard ([`packages/dashboard/src/store.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/dashboard/src/store.ts)) fetches the JSON graph from [`/.understand-anything/file-content.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//.understand-anything/file-content.json) (protected by access token) and visualizes it using force-directed layouts. The interface displays a right-hand sidebar with **Info** panels showing project overviews and layer details, and a **Files** tree explorer, all driven by the same knowledge graph produced by the agent pipeline.

## Summary

- The **Project-Scanner Agent** (`scan-project.mjs`, `extract-import-map.mjs`) creates the canonical file inventory and import map using tree-sitter parsing
- The **File-Analyzer Agent** (`extract-structure.mjs`) extracts functions, classes, and metrics into batched JSON fragments conforming to [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts)
- The **Graph-Reviewer Agent** merges batch fragments into a validated [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json) with unique node IDs and verified edges
- The **Architecture-Analyzer Agent** ([`ua-arch-analyze.js`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-arch-analyze.js)) assigns architectural layers (`layer:api`, `layer:service`) and computes deployment topology
- The **Core Orchestration** ([`src/understand-chat.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/src/understand-chat.ts)) transforms the graph into LLM-ready prompts with proper token management
- The entire pipeline is deterministic, cache-friendly, and extensible via the agent specification files in `understand-anything-plugin/agents/`

## Frequently Asked Questions

### What makes the Egonex AI multi-agent system deterministic?

The system achieves determinism by using scripted agents (`scan-project.mjs`, `extract-structure.mjs`, [`ua-arch-analyze.js`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-arch-analyze.js)) that produce identical outputs for identical inputs, with no stochastic operations during the scanning and analysis phases. Each agent validates its inputs (checking node-ID uniqueness in [`graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-reviewer.md)) and produces schema-compliant JSON outputs that downstream agents consume predictably.

### How does the File-Analyzer handle different programming languages?

The File-Analyzer uses **tree-sitter** parsers to extract structural elements from each file, enabling language-agnostic analysis of functions, classes, and imports. It detects languages during the Project-Scanner phase and applies the appropriate tree-sitter grammar while mapping all extractions to the unified schema defined in [`packages/core/src/types.ts`](https://github.com/Egonex-AI/Understand-Anything/blob/main/packages/core/src/types.ts).

### Where is the knowledge graph stored during pipeline execution?

Intermediate artifacts reside in `.understand-anything/intermediate/`, including [`ua-scan-files.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-scan-files.json), [`ua-import-map-output.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/ua-import-map-output.json), `batch-<n>.json` fragments, and the final [`knowledge-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/knowledge-graph.json). The dashboard consumes this data from [`/.understand-anything/file-content.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main//.understand-anything/file-content.json) after the Graph-Reviewer completes the merge process.

### Can I run individual agents without executing the full pipeline?

Yes, the agent specifications in `understand-anything-plugin/agents/` define standalone operations. You can execute `scan-project.mjs` independently to generate just the file inventory, or run `extract-structure.mjs` against specific file batches. However, the Architecture-Analyzer requires the complete merged graph from the Graph-Reviewer to compute layer assignments and deployment topology.