# How Agents Write Intermediate Results to Disk During Pipeline Execution in Egonex-AI

> Learn how Egonex AI agents write intermediate results to disk as JSON files during pipeline execution. This enables deterministic and parallel stage processing.

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

---

**In the Egonex-AI Understand-Anything pipeline, each agent persists its output by writing JSON files to a dedicated intermediate directory at `.understand-anything/intermediate/<agent-output>.json`, enabling deterministic, parallelizable stage execution.**

The Understand-Anything repository implements a multi-agent architecture where specialized agents (Project-Scanner, File-Analyzer, Architecture-Analyzer, and others) analyze codebases sequentially. Each agent follows a strict disk-persistence contract to write intermediate results to disk, ensuring that downstream phases can read, merge, and validate data without memory-bound constraints.

## The Intermediate Directory Convention

Every agent in the pipeline adheres to a three-step persistence pattern. First, the agent ensures the working directory exists using `mkdir -p`. Second, it writes a JSON payload containing its analysis results. Third, it signals completion by returning the file path for downstream consumption.

The canonical path is always `<project-root>/.understand-anything/intermediate/<name>.json`. This location lives outside the version-controlled source tree, preventing repository pollution while maintaining deterministic replay capabilities.

### Why Use a Dedicated Intermediate Folder?

Three architectural principles drive this design:

- **Determinism** – Each agent produces pure data files, enabling pipeline replay by simply re-reading JSON outputs.
- **Parallelism** – Concurrent File-Analyzer agents avoid collisions by embedding batch indices in filenames (e.g., [`batch-3-part-1.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/batch-3-part-1.json)).
- **Isolation** – The `.understand-anything` directory keeps transient analysis data separate from source code.

## Agent-Specific Write Locations

Each agent writes to a predetermined filename defined in its Markdown specification:

- **Project-Scanner** writes the initial codebase scan to [`scan-result.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/scan-result.json) according to [`project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/project-scanner.md) at line 229.
- **File-Analyzer** emits per-batch graph fragments to `batch-<index>.json`, or splits large outputs into `batch-<index>-part-<k>.json` when node counts exceed 60 or edge counts exceed 120, as defined in [`file-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/file-analyzer.md) at line 500.
- **Architecture-Analyzer** persists layer descriptions to [`layers.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/layers.json) (line 476 of [`architecture-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/architecture-analyzer.md)).
- **Tour-Builder** generates navigation data in [`tour.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tour.json) (line 374 of [`tour-builder.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/tour-builder.md)).
- **Graph-Reviewer** outputs validation results to [`review.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/review.json) (line 235 of [`graph-reviewer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/graph-reviewer.md)).
- **Domain-Analyzer** writes domain-specific analysis to [`domain-analysis.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-analysis.json) (line 120 of [`domain-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/domain-analyzer.md)).

## Implementation Examples

### Project-Scanner Writing scan-result.json

The first agent in the pipeline creates the intermediate directory and writes the initial scan results:

```bash
mkdir -p "$PROJECT_ROOT/.understand-anything/intermediate"
cat > "$PROJECT_ROOT/.understand-anything/intermediate/scan-result.json" <<'EOF'
{
  "name": "my-project",
  "description": "A brief description …",
  "languages": ["typescript", "markdown"],
  "frameworks": ["React", "Vite"],
  "files": [
    {"path":"src/index.ts","language":"typescript","sizeLines":150,"fileCategory":"code"},
    {"path":"README.md","language":"markdown","sizeLines":45,"fileCategory":"docs"}
  ],
  "totalFiles":42,
  "filteredByIgnore":0,
  "estimatedComplexity":"moderate",
  "importMap":{"src/index.ts":["src/utils.ts"]}
}
EOF

```

*Source:* [`project-scanner.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/project-scanner.md), lines 229–230.

### File-Analyzer Handling Large Batches

When processing large codebases, the File-Analyzer splits outputs to avoid memory constraints:

```bash
BATCH=3
if (( nodeCount > 60 || edgeCount > 120 )); then
  # split output into multiple parts

  for part in 1 2; do
    cat > "$PROJECT_ROOT/.understand-anything/intermediate/batch-${BATCH}-part-${part}.json" <<'EOF'
    { "nodes":[…], "edges":[…] }
EOF
  done
else
  # single-file mode

  cat > "$PROJECT_ROOT/.understand-anything/intermediate/batch-${BATCH}.json" <<'EOF'
  { "nodes":[…], "edges":[…] }
EOF
fi

```

*Source:* [`file-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/file-analyzer.md), lines 500–509.

### Architecture-Analyzer Writing layers.json

The Architecture-Analyzer persists module layer information:

```bash
mkdir -p "$PROJECT_ROOT/.understand-anything/intermediate"
cat > "$PROJECT_ROOT/.understand-anything/intermediate/layers.json" <<'EOF'
[
  {"id":"layer-1","type":"module","nodes":["src/index.ts"]},
  {"id":"layer-2","type":"service","nodes":["src/server.ts"]}
]
EOF

```

*Source:* [`architecture-analyzer.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/architecture-analyzer.md), line 476.

## Downstream Consumption and Cleanup

Downstream phases such as [`merge-batch-graphs.py`](https://github.com/Egonex-AI/Understand-Anything/blob/main/merge-batch-graphs.py) and `assemble-reviewer.mjs` read these JSON files directly from the intermediate folder. After assembling the final knowledge graph, the orchestrator defined in [`skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand/SKILL.md) cleans the intermediate directory to prevent artifact accumulation.

## Summary

- Agents write **only JSON** to `.understand-anything/intermediate/<name>.json`.
- **File-Analyzer** uses batch-indexed filenames to support parallel execution without collisions.
- All agents use the `mkdir -p` pattern to ensure directory existence before writing.
- Downstream tools read these files to assemble the final knowledge graph.
- The intermediate folder stays outside the source tree for clean isolation.

## Frequently Asked Questions

### What file format do agents use for intermediate results?

Agents write exclusively **JSON** files. This standardization ensures that downstream Python and JavaScript utilities can parse outputs without format conversion logic.

### How does the pipeline handle concurrent agent execution?

The File-Analyzer agent embeds batch indices in filenames (e.g., [`batch-3.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/batch-3.json) or [`batch-3-part-2.json`](https://github.com/Egonex-AI/Understand-Anything/blob/main/batch-3-part-2.json)). This naming convention prevents write collisions when multiple agents run simultaneously, allowing safe parallel processing of large codebases.

### Where are the intermediate files located?

Intermediate files reside in `.understand-anything/intermediate/` relative to the project root. This location is created on-demand by each agent and is excluded from version control to keep the repository clean.

### Who cleans up the intermediate directory?

The pipeline orchestrator defined in [`skills/understand/SKILL.md`](https://github.com/Egonex-AI/Understand-Anything/blob/main/skills/understand/SKILL.md) removes the intermediate folder after downstream phases have consumed the JSON files and assembled the final knowledge graph.