Tree-sitter + LLM Hybrid Analysis vs. Pure Static Analysis in Understand Anything

Understand Anything combines deterministic Tree-sitter parsing with LLM semantic enrichment to generate knowledge graphs that are both structurally exact and semantically rich, overcoming the limitations of pure static analysis which cannot infer meaning or context.

The open-source Understand Anything repository (Egonex-AI/Understand-Anything) implements a sophisticated code analysis pipeline that merges deterministic syntax parsing with large language model reasoning. This Tree-sitter + LLM hybrid analysis approach generates a unified knowledge graph containing precise dependency edges alongside natural-language summaries, architectural layer assignments, and complexity ratings. Unlike pure static analysis tools that rely solely on syntactic patterns, this hybrid methodology captures both the structural realities and the semantic intent of your codebase.

The Hybrid Architecture: Deterministic Parsing Meets AI Reasoning

The system architecture cleanly separates structural extraction from semantic interpretation, allowing each layer to operate with distinct guarantees and capabilities.

Deterministic Structural Extraction with Tree-sitter

At the foundation lies the TreeSitterPlugin, implemented in packages/core/src/plugins/tree-sitter-plugin.ts. This component loads language-specific grammars as WASM modules and executes deterministic parsing synchronously to produce concrete syntax trees.

The plugin extracts immutable structural facts including:

• Import and export declarations
• Function and class definitions
• Call-site relationships and dependency graphs

These elements form a structural graph stored in StructuralAnalysis objects that remain reproducible across identical code versions. Because Tree-sitter parsing is deterministic, the system guarantees that unchanged files produce identical output, enabling reliable incremental updates via file fingerprinting (see packages/core/src/fingerprint.ts).

Semantic Enrichment via LLM Analysis

The semantic layer resides in packages/core/src/analyzer/llm-analyzer.ts, which orchestrates five specialized agents: project-scanner, file-analyzer, architecture-analyzer, tour-builder, and graph-reviewer.

The LLM consumes both the deterministic structure and raw source text to generate:

• Natural-language file summaries and function descriptions
• Business-domain tags and complexity ratings
• Architectural layer assignments
• Contextual explanations for dashboard features

Functions like buildFileAnalysisPrompt format structured prompts for the LLM, while parseFileAnalysisResponse validates and normalizes the JSON output before integration into the knowledge graph.

How the Hybrid Analysis Pipeline Works

The pipeline executes in five distinct stages, ensuring that structural accuracy validates semantic assumptions before storage.

1. Discovery – The project-scanner agent enumerates source files and identifies language configurations via language-registry.ts.

2. Structural Extraction – For each file, TreeSitterPlugin.analyzeFile returns a StructuralAnalysis object containing functions, classes, imports, and exports.

3. LLM Enrichment – The file-analyzer constructs prompts using buildFileAnalysisPrompt, sends them to the LLM, and parses responses with parseFileAnalysisResponse.

4. Graph Merge – packages/core/src/analyzer/graph-builder.ts synthesizes deterministic edges (imports, call graphs) with LLM-generated metadata (tags, descriptions) into a unified knowledge graph.

5. Validation – The graph-reviewer optionally executes a second LLM pass to verify completeness and consistency of the generated graph.

This architecture enables incremental updates: the system fingerprints files and only re-runs LLM analysis for changed content, dramatically reducing token usage while maintaining graph integrity.

Code Example: Implementing the Hybrid Analyzer

The following TypeScript script demonstrates the two-step hybrid process without full agent orchestration. It manually invokes the Tree-sitter parser and LLM analyzer to process a single file:

import { TreeSitterPlugin } from "./understand-anything-plugin/packages/core/src/plugins/tree-sitter-plugin.js";
import { buildFileAnalysisPrompt, parseFileAnalysisResponse } from "./understand-anything-plugin/packages/core/src/analyzer/llm-analyzer.js";

// 1️⃣ Initialise the parser (await init before using)
const parser = new TreeSitterPlugin();
await parser.init();

// 2️⃣ Read a source file (any .ts/.js file)
const filePath = "src/example.ts";
const content = await import("fs/promises").then(fs => fs.readFile(filePath, "utf8"));

// 3️⃣ Structural analysis via Tree‑sitter
const struct = parser.analyzeFile(filePath, content);
console.log("Structural facts:", struct);

// 4️⃣ Build LLM prompt using the same source + optional project context
const prompt = buildFileAnalysisPrompt(filePath, content, "A small demo project");

// 5️⃣ Call your LLM (placeholder)
async function callLLM(prompt: string): Promise<string> {
  // Replace with your provider: e.g. Claude, OpenAI, Anthropic, etc.
  return `{
    "fileSummary": "Utility module exporting helpers.",
    "tags": ["utility","helper"],
    "complexity": "simple",
    "functionSummaries": {"doWork":"Performs work."},
    "classSummaries": {}
  }`;
}
const llmResponse = await callLLM(prompt);

// 6️⃣ Parse the LLM JSON payload
const analysis = parseFileAnalysisResponse(llmResponse);
console.log("LLM‑enriched analysis:", analysis);

This example showcases the deterministic-then-semantic workflow: Tree-sitter provides guaranteed structural facts, while the LLM adds contextual meaning that pure parsing cannot extract.

Tree-sitter + LLM Hybrid Analysis vs. Pure Static Analysis

Understanding the distinction between these approaches clarifies when to implement hybrid pipelines.

Pure static analysis relies exclusively on syntactic patterns and symbolic execution. While it can compute reachability graphs and dependency trees, it cannot infer business logic, generate natural-language summaries, or classify architectural layers without extensive manual rule engineering.

Hybrid analysis combines:

• Exact graph edges from Tree-sitter that never change unless code changes, providing reproducible dependency maps
• Rich semantic metadata from LLMs that power the dashboard's "guided tours" and search-by-meaning features

The hybrid approach maintains the performance benefits of deterministic parsing—such as incremental updates via fingerprint.ts—while adding the interpretive capabilities necessary for modern AI-assisted development tools.

Summary

• Tree-sitter + LLM hybrid analysis in Understand Anything merges deterministic parsing (tree-sitter-plugin.ts) with AI-powered semantic enrichment (llm-analyzer.ts) to create comprehensive knowledge graphs.
• The structural layer guarantees exact extraction of imports, exports, functions, and call graphs through the TreeSitterPlugin class.
• The semantic layer employs five specialized agents to generate descriptions, tags, and complexity ratings via buildFileAnalysisPrompt and related functions.
• Incremental updates are possible because Tree-sitter output is deterministic, allowing the system to fingerprint files and re-run LLM analysis only for changed content.
• Unlike pure static analysis, the hybrid approach provides human-readable explanations and business-domain context essential for interactive code exploration.

Frequently Asked Questions

What is Tree-sitter + LLM hybrid analysis?

Tree-sitter + LLM hybrid analysis is a dual-phase code analysis technique that first uses Tree-sitter to deterministically parse source code into concrete syntax trees, then uses large language models to interpret that structure and generate semantic metadata like descriptions, tags, and complexity ratings. This combination produces knowledge graphs that are both structurally accurate and semantically meaningful.

How does Understand Anything handle incremental updates?

The system leverages file fingerprinting (implemented in packages/core/src/fingerprint.ts) to detect changed files. Since Tree-sitter parsing is deterministic and reproducible, unchanged files bypass re-processing. Only modified files trigger new LLM analysis calls, significantly reducing token consumption and API costs while keeping the knowledge graph synchronized with the codebase.

What are the limitations of pure static analysis compared to the hybrid approach?

Pure static analysis can extract syntactic relationships like imports and function calls, but it cannot infer business-domain meaning, generate natural-language summaries, or classify code by architectural layers without extensive manual heuristics. The hybrid approach overcomes these limitations by using LLMs to interpret code context, enabling features like "guided tours" and semantic search that pure static analysis cannot support.

Which source files contain the core hybrid logic?

The primary implementation files are:

• packages/core/src/plugins/tree-sitter-plugin.ts – Contains the TreeSitterPlugin class for deterministic parsing
• packages/core/src/analyzer/llm-analyzer.ts – Houses buildFileAnalysisPrompt, parseFileAnalysisResponse, and the five-agent orchestration logic
• packages/core/src/analyzer/graph-builder.ts – Merges structural and semantic data into the final graph representation

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