How Munder Difflin Handles Agent Coordination with a Shared Orchestration Layer

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 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 lines 33-42) grants exclusive rights to modify the roster (registry.json), task ledger (tasks.json), and shared plan (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 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 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 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)

The HiveTask interface (lines 106-130 in 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)

The orchestrator maintains board.md as the single source of truth for team coordination. As documented in 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 lines 73-82【/cache/repos/github.com/chaitanyagiri/munder-difflin/main/src/renderer/src/hooks/useHive.ts#L73-L82】:

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 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

// 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

// 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

// 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, confirms no existing task covers this, and creates a task in 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	Core coordination: registry, router, message schemas, task interface
src/shared/godIdentity.ts	Orchestrator naming constants and resolution helpers
src/main/config.ts	Runtime configuration: model selection, spawn permissions
src/renderer/src/hooks/useHive.ts	UI-layer orchestrator bootstrap and prompt injection
HIVE.md	Architecture design document: mailbox model, responsibilities, invariants
src/shared/agentProvider.ts	LLM provider configuration for orchestrator reasoning
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, tasks.json, and 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.

How does the router prevent message loss or duplication?

The router uses atomic file moves (renameSync) combined with a cursor file (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.

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.

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