Munder Difflin Hive Directory Structure: A Complete Guide to the Multi-Agent File System

The Munder Difflin hive directory structure is a file-centric coordination layer located at <harnessHome>/hive/ that uses atomic JSON messages, append-only logs, and Git-based versioning to enable safe multi-agent collaboration.

The Hive serves as the on-disk "brain" of the Munder Difflin multi-agent system, implemented in the chaitanyagiri/munder-difflin repository. This directory structure is deliberately designed to be simple and file-centric, allowing each agent to read and write its own slice safely while the Electron main process handles coordination and versioning through Git.

Root Directory Structure

The Hive root contains five critical files that govern the entire multi-agent ecosystem. According to the design documentation in HIVE.md, these files establish the contract, roster, shared state, task ledger, and event stream.

PROTOCOL.md defines the on-disk contract that agents must follow, specifying message formats and operational hooks.

registry.json acts as the master roster, tracking every agent’s ID, role, capabilities, and current status in a single JSON file.

board.md functions as a shared blackboard where agents co-author plans. The design enforces a single-writer constraint—only the God-agent can modify this file—to prevent concurrent edit conflicts.

tasks.json maintains the task ledger, containing task IDs, assignees, specifications, current status, and result references for the entire system.

log.jsonl provides an append-only event feed that powers the UI activity stream. Every mutation across the system is recorded here, creating a linear history that agents can replay.

Agent-Specific Directory Layout

Each agent operates within its own isolated subdirectory under hive/agents/<agentId>/. This agent-scoped architecture guarantees single-writer-per-file safety, as agents only write within their own folders.

The agent directory contains:

• identity.md — A static markdown description of the agent’s role and capabilities
• memory.md — Long-term markdown memory storage for the specific agent
• inbox/ — Directory containing inbound messages as individual JSON files (<ts>-<msgId>.json)
• inbox/.done/ — Archive of processed messages serving as an audit trail (messages are never deleted)
• outbox/ — Directory for outbound messages written by the agent (<ts>-<msgId>.json)
• cursor.json — Tracks the last processed message ID to prevent re-processing

Design Principles and Safety Mechanisms

The Munder Difflin hive directory structure implements several architectural safeguards to ensure data integrity in a multi-process environment.

Atomic Message Writes — Agents write messages atomically using a temporary file followed by a rename operation. This pattern prevents Git merge conflicts and ensures files are never partially written.

Append-Only Log — The log.jsonl file operates as an append-only stream. Every mutation is recorded here, and agents maintain their own cursor.json to track processing position rather than deleting or modifying historical entries.

Single-Writer Constraints — The board.md file enforces single-writer semantics through the God-agent role, eliminating concurrent modification risks.

Git as Audit Layer — Only the main harness process commits changes to the Hive repository. This design ensures a clean linear history and prevents .git/index.lock contention that would occur if multiple agents attempted simultaneous commits.

Working with the Hive Programmatically

Interacting with the Hive requires understanding the file-based API. Below are TypeScript implementations demonstrating inbox reading, atomic message writing, and log appending.

Reading an Agent’s Inbox

To retrieve messages from an agent’s inbox, read each JSON file individually and parse the contents:

import { readdir, readFile } from 'fs/promises';
import path from 'path';

async function readInbox(agentId: string) {
  const inboxDir = path.resolve('hive/agents', agentId, 'inbox');
  const files = await readdir(inboxDir);
  const messages = await Promise.all(
    files.map(f => readFile(path.join(inboxDir, f), 'utf8').then(JSON.parse))
  );
  return messages;
}

Writing Atomic Outbound Messages

When sending messages, write to a temporary location first, then rename to ensure atomicity:

import { writeFile, rename } from 'fs/promises';
import { tmpdir } from 'os';
import path from 'path';
import { v4 as uuid } from 'uuid';

async function sendMessage(agentId: string, payload: object) {
  const outbox = path.resolve('hive/agents', agentId, 'outbox');
  const tmpPath = path.join(tmpdir(), `${uuid()}.tmp`);
  await writeFile(tmpPath, JSON.stringify(payload, null, 2));
  const finalPath = path.join(outbox, `${Date.now()}-${uuid()}.json`);
  await rename(tmpPath, finalPath);     // atomic move
}

Appending to the System Log

The main process appends entries to the shared log using simple file append operations:

import { appendFile } from 'fs/promises';
import path from 'path';

async function appendLog(entry: object) {
  const logPath = path.resolve('hive/log.jsonl');
  await appendFile(logPath, JSON.stringify(entry) + '\n');
}

Summary

• The Hive resides at <harnessHome>/hive/ and serves as the Git-backed persistence layer for the Munder Difflin multi-agent system.
• Root-level files (PROTOCOL.md, registry.json, board.md, tasks.json, log.jsonl) define contracts, roster, shared state, and audit trails.
• Each agent operates within hive/agents/<agentId>/ with isolated directories for identity, memory, inbox, outbox, and cursor tracking.
• Atomic writes via temporary files and rename operations prevent corruption and Git conflicts.
• Only the Electron main process commits to Git, ensuring linear history and avoiding lock contention.

Frequently Asked Questions

Where is the Munder Difflin hive directory located?

The Hive directory is located at <harnessHome>/hive/ relative to the application root. This path is configured as a Git repository that only the Electron main process commits to, ensuring centralized version control of all agent state and messages.

How does the Hive prevent file corruption during concurrent writes?

The system prevents corruption through atomic file operations. Agents write to temporary files in the OS temp directory, then use rename to move files into their final destination (such as hive/agents/<agentId>/outbox/). This ensures that JSON files appear fully written or not at all, eliminating partial write states.

What is the purpose of the cursor.json file in agent directories?

The cursor.json file tracks the last message ID processed by that specific agent. Since log.jsonl is append-only and inbox messages are archived rather than deleted, agents use this cursor to maintain their position in the event stream and avoid re-processing historical messages.

How does the board.md file maintain consistency across agents?

Consistency is enforced through a single-writer policy. Only the God-agent has write permissions to board.md, preventing concurrent modification conflicts. Other agents read this file to coordinate plans but route all modifications through the designated God-agent process.

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