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

> Explore the Munder Difflin hive directory structure a file-centric coordination layer enabling safe multi-agent collaboration with atomic JSON messages Git versioning and append-only logs.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: how-to-guide
- Published: 2026-08-27

---

**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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/cursor.json) to track processing position rather than deleting or modifying historical entries.

**Single-Writer Constraints** — The [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```typescript
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:

```typescript
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:

```typescript
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/PROTOCOL.md), [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json), [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md), [`tasks.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md), preventing concurrent modification conflicts. Other agents read this file to coordinate plans but route all modifications through the designated God-agent process.