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

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) 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, recording every internal import edge.

This stage produces two critical artifacts: ua-scan-files.json containing the canonical file list, and ua-import-map-output.json mapping all import relationships.

File-Analyzer Agent: Structural Extraction

The File-Analyzer Agent (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. 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) 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 ready for architectural analysis.

Architecture-Analyzer Agent: Layer Detection

The Architecture-Analyzer Agent (agents/architecture-analyzer.md) runs the deterministic Node.js script 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 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 and 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:

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

# Count total nodes in the knowledge graph

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

Launch the interactive dashboard to visualize results:

pnpm --filter @understand-anything/dashboard dev

The dashboard loads the graph from /.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:

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) fetches the JSON graph from /.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
• The Graph-Reviewer Agent merges batch fragments into a validated knowledge-graph.json with unique node IDs and verified edges
• The Architecture-Analyzer Agent (ua-arch-analyze.js) assigns architectural layers (layer:api, layer:service) and computes deployment topology
• The Core Orchestration (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) 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) 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.

Where is the knowledge graph stored during pipeline execution?

Intermediate artifacts reside in .understand-anything/intermediate/, including ua-scan-files.json, ua-import-map-output.json, batch-<n>.json fragments, and the final knowledge-graph.json. The dashboard consumes this data from /.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.

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