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

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).
• 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 according to 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 at line 500.
• Architecture-Analyzer persists layer descriptions to layers.json (line 476 of architecture-analyzer.md).
• Tour-Builder generates navigation data in tour.json (line 374 of tour-builder.md).
• Graph-Reviewer outputs validation results to review.json (line 235 of graph-reviewer.md).
• Domain-Analyzer writes domain-specific analysis to domain-analysis.json (line 120 of 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:

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, lines 229–230.

File-Analyzer Handling Large Batches

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

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, lines 500–509.

Architecture-Analyzer Writing layers.json

The Architecture-Analyzer persists module layer information:

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, line 476.

Downstream Consumption and Cleanup

Downstream phases such as 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 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 or 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 removes the intermediate folder after downstream phases have consumed the JSON files and assembled the final knowledge graph.

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