Batch Processing Strategy for Large Codebases in Understand Anything: A 5-Step Technical Breakdown

Understand Anything processes large codebases by splitting files into deterministic batches of 20-30 files each, dispatching up to 5 concurrent file-analyzer sub-agents, and merging the resulting JSON fragments using a strict naming convention to avoid token limit exceeded errors.

The understand skill in the Understand Anything repository employs a sophisticated batch processing strategy for large codebases that keeps LLM requests within token limits while maximizing parallel execution. When analyzing repositories with thousands of files, the system deterministically partitions the workload through a multi-phase pipeline that separates batch construction from analysis execution. This approach ensures that even monorepos with hundreds of thousands of lines of code can be processed without hitting model context windows or losing cross-file relationships.

The 5-Step Batch Processing Pipeline

The batch processing strategy for large codebases operates through five tightly-coupled components that transform a raw repository scan into an assembled knowledge graph.

Step 1: Deterministic Batch Construction

The pipeline begins with compute-batches.mjs, a deterministic script located at skills/understand/compute-batches.mjs that scans the project-wide scan-result.json produced by the project-scanner agent. This script generates batches.json, where each entry contains a list of file descriptors including path, language, sizeLines, and fileCategory, along with pre-resolved batchImportData and a neighborMap of cross-batch symbols.

By extracting import information once during the scan phase using Tree-sitter, subsequent sub-agents reuse the already-resolved batchImportData, eliminating duplicate parsing overhead.

Step 2: File-Analyzer Dispatch with Concurrency Control

During Phase 2 — ANALYZE (documented in skills/understand/SKILL.md), the core skill iterates over batches.json and launches a file-analyzer sub-agent for every batch. The system maintains a default concurrency limit of 5 concurrent agents, though this is configurable within the skill.

Crucially, each LLM prompt includes only the data for that specific batch; the full project file list is not repeated for each request. This token-budget awareness saves thousands of tokens per request, keeping even large analyses within model limits.

Step 3: Chunked Output and Automatic Splitting

Each batch writes its own JSON fragment following the exact naming pattern batch-<idx>.json. If a batch would exceed the edge/node limits (≥60 nodes or ≥120 edges), the fragment is automatically split into numbered parts using the pattern batch-<idx>-part-<k>.json.

The output naming logic is strictly enforced in the file-analyzer agent specification (agents/file-analyzer.md, lines 482-489). Any deviation from the regex pattern batch-(\d+)(?:-part-(\d+))?\.json results in silent discarding of the fragment, making strict naming essential for successful assembly.

Step 4: Merge and Verification

After all sub-agents complete, the orchestrator executes merge-batch-graphs.py (referenced in the "Phase 2 — ANALYZE" documentation) to combine all batch fragments into assembled-graph.json. The merge script uses the exact filename pattern to locate files and validates that every imports edge count matches the sum of batchImportData entries.

This verification step guarantees that no cross-batch relationships are lost during the parallel processing of large codebases.

Step 5: Progress Reporting

While batches are processed, the skill outputs concise progress lines such as Analyzing batch 3/12 (files: src/app.ts, src/util.ts, …) to provide real-time visibility into the analysis state. This feedback appears in the console output defined in SKILL.md (lines 30-34), allowing users to track progress across potentially hundreds of files.

Why This Scales to Large Codebases

The batch processing strategy for large codebases succeeds through four specific architectural decisions:

• Deterministic pre-processing – Tree-sitter extracts import information once during scanning; later agents reuse batchImportData without re-parsing.
• Token-budget awareness – Sending only the batch's file list instead of the full project list keeps LLM requests within limits, even for projects with thousands of files.
• Parallelism – Up to five file-analyzer agents run concurrently, each handling 20-30 files, reducing wall-clock time from hours to minutes for typical monorepos.
• Robust merging – The merge script's regex pattern ensures all fragments are found, and mismatches trigger errors rather than silent data loss.

The design rationale and token-budget calculations are documented in the Semantic Batching and Output Chunking Design specification.

Working with Batches: Practical Examples

Running the Full Analysis

Execute the complete pipeline with automatic batching:

# From the repo root – the skill builds the plugin if needed,

# computes batches, and launches file-analyzer agents.

understand

Inspecting Generated Batches

Review the batch structure before analysis:

cat .understand-anything/intermediate/batches.json | jq '.batches[] | {idx: .batchIndex, files: .batchFiles | map(.path)}'

Debugging a Single Batch

Re-run a specific batch manually:

# Re-run batch 7 only

BATCH=7
cat .understand-anything/intermediate/batches.json \
  | jq ".batches[] | select(.batchIndex == $BATCH)" \
  > .understand-anything/tmp/batch-$BATCH.json

# Dispatch the file-analyzer for that batch

understand --batch $BATCH

Merging After Custom Runs

Consolidate fragments manually:

python ./understand-anything-plugin/skills/understand/merge-batch-graphs.py .

# Result: .understand-anything/intermediate/assembled-graph.json

Expected Console Output

During execution, expect progress reporting like:

[Phase 2/7] Analyzing files — 342 files in 12 batches (up to 5 concurrent)...
Analyzing batch 1/12 (files: src/index.ts, src/util.ts, src/config.ts)
Analyzing batch 2/12 (files: src/api/auth.ts, src/api/user.ts, src/api/utils.ts)
… 
Phase 2 complete. All 12 batches analyzed.

Summary

• The compute-batches.mjs script deterministically creates batches.json from the project scan, resolving imports and cross-batch dependencies upfront.
• The system launches up to 5 concurrent file-analyzer agents by default, with each agent receiving only its specific batch data to conserve tokens.
• Output files follow the strict regex pattern batch-(\d+)(?:-part-(\d+))?.json; deviations are silently discarded during merge.
• The merge-batch-graphs.py script validates cross-batch imports edges against batchImportData totals to ensure relationship integrity.
• Large batches automatically split when exceeding 60 nodes or 120 edges, preventing individual LLM responses from exceeding token limits.

Frequently Asked Questions

How does Understand Anything handle batches that exceed token limits?

When a batch exceeds the edge/node limits (≥60 nodes or ≥120 edges), the file-analyzer automatically splits the output into numbered parts following the pattern batch-<idx>-part-<k>.json. The merge script recognizes these parts using the regex batch-(\d+)(?:-part-(\d+))?.json and reassembles them into the final graph, ensuring no single LLM request exceeds model constraints.

What is the default concurrency limit for batch processing?

The system defaults to 5 concurrent file-analyzer agents during the analysis phase. This limit is configurable within the skill settings, but the default strikes a balance between parallel speed and resource consumption when processing large codebases.

How are cross-batch dependencies preserved during merging?

During the initial batch construction in compute-batches.mjs, the system generates a neighborMap of cross-batch symbols and includes batchImportData in each batch descriptor. The merge script (merge-batch-graphs.py) validates that every imports edge count in the final graph matches the sum of batchImportData entries across all fragments, guaranteeing no relationships are lost.

Can I run a single batch manually for debugging?

Yes. Extract the specific batch from batches.json using jq, save it to .understand-anything/tmp/batch-<idx>.json, and invoke the skill with the --batch flag: understand --batch 7. This allows you to re-run or debug individual batches without reprocessing the entire codebase.

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