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

> Learn the 5-step batch processing strategy for large codebases in Understand Anything. Discover how to split files, dispatch agents, and merge JSON to avoid token limits.

- Repository: [Egonex/Understand-Anything](https://github.com/Egonex-AI/Understand-Anything)
- Tags: how-to-guide
- Published: 2026-06-23

---

**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](https://github.com/Egonex-AI/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/scan-result.json) produced by the `project-scanner` agent. This script generates [`batches.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand/SKILL.md)), the core skill iterates over [`batches.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-batch-graphs.py) (referenced in the "Phase 2 — ANALYZE" documentation) to combine all batch fragments into [`assembled-graph.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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](https://github.com/Egonex-AI/Understand-Anything/blob/main/docs/superpowers/specs/2026-05-24-semantic-batching-and-output-chunking-design.md) specification.

## Working with Batches: Practical Examples

### Running the Full Analysis

Execute the complete pipeline with automatic batching:

```bash

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

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

```

### Debugging a Single Batch

Re-run a specific batch manually:

```bash

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

```bash
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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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`](https://github.com/Egonex-AI/Understand-Anything/blob/main/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.