# How Munder Difflin Handles Agent Coordination with a Shared Orchestration Layer

> Discover how Munder Difflin achieves agent coordination using a shared orchestration layer with a central God agent and Git-backed mailboxes. Learn about Michael's routing.

- Repository: [Chaitanya Giri/munder-difflin](https://github.com/chaitanyagiri/munder-difflin)
- Tags: internals
- Published: 2026-08-28

---

**Munder Difflin implements a file-based shared orchestration layer where a central God agent named Michael routes messages between autonomous CLI agents using atomic Git-backed mailboxes.**

The **munder-difflin** repository provides a multi-agent platform that transforms independent Claude Code instances into a coordinated "hive" of collaborators. At its core lies a durable, auditable coordination system built entirely on local files, eliminating external dependencies while ensuring deterministic behavior and complete user control.

## The God Orchestrator: Central Authority for Agent Coordination

Every hive operates under the supervision of a **God orchestrator**—a privileged agent that owns all shared state and adjudicates cross-agent workflows.

- **Default identity**: The orchestrator is named **Michael** by default, defined in [`src/shared/godIdentity.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/godIdentity.ts) as `DEFAULT_GOD_NAME = 'Michael'`【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/src/shared/godIdentity.ts#L3-L10】
- **Privileged status**: The `isGod` flag in agent metadata ([`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) lines 33-42) grants exclusive rights to modify the roster ([`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json)), task ledger ([`tasks.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/tasks.json)), and shared plan ([`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md))
- **Exclusive write access**: The Electron main process acts as the sole writer to the on-disk hive, preventing race conditions and merge conflicts

The God orchestrator serves three critical functions in agent coordination:

1. **Request triage**: Examines inbound messages and routes routine work to specialist agents
2. **Escalation handling**: Forwards critical or ambiguous decisions to human operators
3. **State maintenance**: Updates the shared blackboard and task assignments to reflect current priorities

## The Router: Message Delivery with Atomic Guarantees

The **router** in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) implements the actual message transport between agents, enforcing the mailbox/actor model through file system operations.

**Delivery mechanism**:

- Agents write JSON messages to their `outbox/` directory
- The router watches for new files and **atomically moves** them to recipient `inbox/` directories
- A [`cursor.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/cursor.json) tracks processing position for idempotent delivery
- Every delivery is logged to `log.jsonl` and committed to Git for full auditability

This design satisfies the **single-writer-per-file** invariant critical for safe coordination—no two processes ever compete to modify the same file.

## Message Schema: FIPA-Lite Communication Protocol

Agent communication in Munder Difflin follows a structured message format defined by the `HiveMessage` interface in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) lines 56-67【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/src/main/hive.ts#L54-L66】:

| Field | Purpose |
|-------|---------|
| `from` | Sender agent ID |
| `to` | Recipient: agent ID, `god`, or `broadcast` |
| `act` | Message type: `request`, `inform`, `query-ref`, `agree`, `refuse`, etc. |
| `subject` | Topic or task identifier |
| `body` | Payload (arbitrary JSON-serializable content) |
| `hop_count` | TTL counter to prevent infinite routing loops |
| `requires_reply` | Boolean flag for synchronous-style interactions |
| `needs_human` | Escalation flag for human-in-the-loop decisions |

The `to: 'god'` destination enables any agent to reach the orchestrator directly, while `broadcast` allows one-to-many communication patterns.

## Shared State Components

### Task Ledger ([`tasks.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/tasks.json))

The `HiveTask` interface (lines 106-130 in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts))【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/src/main/hive.ts#L106-L130】 defines work items with:

- Unique task IDs and descriptive titles
- Assignee references and status tracking (`pending`, `active`, `blocked`, `completed`)
- Dependency graphs between tasks
- Linked Q&A threads for human clarification

### Shared Blackboard ([`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md))

The orchestrator maintains [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md) as the **single source of truth** for team coordination. As documented in [`HIVE.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md) §6【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/HIVE.md#L55-L61】, the God agent holds exclusive write access, eliminating merge conflicts that would plague multi-writer approaches.

## Orchestrator Bootstrap and Configuration

### Startup Sequence

The God agent initializes with a structured orientation prompt defined in [`src/renderer/src/hooks/useHive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/renderer/src/hooks/useHive.ts) lines 73-82【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/src/renderer/src/hooks/useHive.ts#L73-L82】:

```typescript
const INITIAL_GOD_PROMPT = [
  "You're online as Michael, the orchestrator of the hive. Get oriented, then start running the floor:",
  "1. Read your memory.md and drain every message in your inbox.",
  "2. Review board.md + tasks.json and the current roster of agents.",
  "3. Check fleet health …",
  "4. Skim COMMANDS.md …",
  "Then begin orchestrating: triage requests, delegate work, keep everyone unblocked."
].join('\n');

await submitToPty(GOD_PTY, INITIAL_GOD_PROMPT, godProvider);

```

This prompt ensures the orchestrator rebuilds complete context from durable state before making coordination decisions.

### Configurable Behaviors

Orchestrator behavior is controlled via [`src/main/config.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/config.ts) lines 207-213【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/src/main/config.ts#L207-L213】:

| Option | Effect |
|--------|--------|
| `config.orchestratorMaySpawn` | Allows God to auto-create new specialist agents |
| `config.godModel` | Selects LLM provider/model for orchestrator reasoning |

## Practical Code Examples

### Sending a Request to the Orchestrator

```typescript
// From any UI component: enqueue a message for Michael
import { useStore } from '@/store/store';

useStore.getState().enqueueMessage(
  'god',                                   // recipient: the orchestrator
  JSON.stringify({
    act: 'request',
    subject: 'Run tests',
    body: 'Please run `npm test` in the current workspace.',
    requires_reply: true,
    needs_human: false,
  })
);

```

### Router Implementation Pattern

```typescript
// Simplified delivery logic from src/main/hive.ts
import { readFileSync, renameSync, appendFileSync } from 'fs';
import { join, basename } from 'path';

interface HiveMessage {
  from: string;
  to: string;
  act: string;
  subject: string;
  body: string;
  hop_count: number;
}

function deliverMessage(msgPath: string, hiveRoot: string, logPath: string): void {
  const msg = JSON.parse(readFileSync(msgPath, 'utf8')) as HiveMessage;
  
  // Atomic move guarantees single-writer semantics
  const inboxDir = join(hiveRoot, 'agents', msg.to, 'inbox');
  const dest = join(inboxDir, basename(msgPath));
  renameSync(msgPath, dest);
  
  // Append-only logging for audit trail
  const logEntry = { ...msg, delivered: true, timestamp: Date.now() };
  appendFileSync(logPath, JSON.stringify(logEntry) + '\n');
}

```

### Agent Role Resolution

```typescript
// From src/shared/agentRole.ts - identifying the orchestrator
export function getRoleDisplayName(meta: AgentMeta): string {
  if (meta.isGod) return 'orchestrator (god)';
  if (meta.specialty) return meta.specialty;
  return 'generalist';
}

```

## Coordination Flow in Practice

A complete coordination cycle demonstrates how Munder Difflin's shared orchestration layer handles real work:

1. **Agent specialization**: "Devin" (frontend specialist) encounters a backend API issue and writes a `request` message to `outbox/`
2. **Router activation**: Main process detects the file, reads `to: 'god'`, and delivers to Michael's `inbox/`
3. **Orchestrator triage**: Michael reads [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md), confirms no existing task covers this, and creates a task in [`tasks.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/tasks.json)
4. **Delegation decision**: Michael assigns to "Hal" (backend specialist) by writing to Hal's `inbox/`
5. **Specialist execution**: Hal processes the request, writes `inform` result to outbox, router delivers to Devin
6. **Completion logging**: State changes commit to Git with full provenance

## Key Source Files

| File | Responsibility |
|------|---------------|
| [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) | Core coordination: registry, router, message schemas, task interface |
| [`src/shared/godIdentity.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/godIdentity.ts) | Orchestrator naming constants and resolution helpers |
| [`src/main/config.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/config.ts) | Runtime configuration: model selection, spawn permissions |
| [`src/renderer/src/hooks/useHive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/renderer/src/hooks/useHive.ts) | UI-layer orchestrator bootstrap and prompt injection |
| [`HIVE.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md) | Architecture design document: mailbox model, responsibilities, invariants |
| [`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts) | LLM provider configuration for orchestrator reasoning |
| [`src/shared/agentRole.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentRole.ts) | Role classification and display utilities |

## Summary

- **Munder Difflin's shared orchestration layer** combines a God agent (Michael), atomic file-based router, and structured messaging to coordinate multiple autonomous CLI agents
- **Single-writer Git-backed state** ensures durability, auditability, and freedom from external services
- **FIPA-lite message schema** enables rich agent communication with built-in escalation paths
- **Configurable orchestrator behavior** allows tuning between autonomous operation and human oversight

## Frequently Asked Questions

### What makes the orchestrator "God" in Munder Difflin?

The God status is a boolean flag (`isGod`) in agent metadata that grants exclusive write access to [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json), [`tasks.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/tasks.json), and [`board.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/board.md). Only one agent per hive holds this status, enforced by the `DEFAULT_GOD_NAME` constant and validation logic in [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts).

### How does the router prevent message loss or duplication?

The router uses **atomic file moves** (`renameSync`) combined with a **cursor file** ([`cursor.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/cursor.json)) that tracks processed messages. File system atomicity guarantees exactly-once delivery, while the append-only `log.jsonl` provides recovery capability if the main process restarts.

### Can I change the orchestrator's name from Michael?

Yes. While `DEFAULT_GOD_NAME = 'Michael'` defines the default, the system resolves God identity through the `isGod` flag rather than hardcoded names. Configure your initial agent with `isGod: true` and any desired `name` value in [`registry.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/registry.json).

### What happens when an agent sends `needs_human: true`?

The orchestrator intercepts such messages and routes them to the human proxy interface instead of resolving autonomously. This implements human-in-the-loop governance while maintaining the same mailbox transport—the human's responses re-enter the system as messages from a special `human` sender ID.