Munder-Difflin Main Modules: A Complete Guide to the Multi-Agent Architecture

Munder-Difflin organizes its codebase into distinct modules centered on Electron's split-process model, with src/main/ handling core orchestration, src/renderer/ powering the React UI, and domain-specific services managing the Hive multi-agent coordination layer.

The Munder-Difflin main modules form a layered platform for orchestrating multiple AI agents through a desktop application. This open-source project, maintained by chaitanyagiri, implements a "hive" pattern where agents communicate via files on disk rather than in-memory message passing. Understanding these modules is essential for extending the platform or integrating custom providers.

Core Electron Architecture

Munder-Difflin follows the standard Electron split-process model with three foundational layers:

Main Process (src/main/)

The main process runs in Node.js and owns all system-level operations. It manages the application lifecycle, spawns child processes, and maintains the on-disk Hive repository.

Key responsibilities include:

• PTY management for terminal emulation
• Git integration and worktree isolation
• Auto-updates and telemetry collection
• Window management and IPC coordination

Primary entry points:

// src/main/index.ts — Application bootstrap
// src/main/hive.ts — Hive coordination layer
// src/main/config.ts — Central configuration
// src/main/telemetry.ts — Usage analytics

Renderer Process (src/renderer/)

The renderer process hosts the React-based UI built with Vite. It displays agents, terminals, and task boards, synchronizing all state through IPC with the main process.

Core components:

// src/renderer/src/App.tsx — Root component
// src/renderer/src/components/AgentStrip.tsx — Agent visualization
// src/renderer/src/components/MemoryPanel.tsx — Semantic memory UI

Preload Scripts (src/preload/)

The preload bridge exposes a limited, secure API to the renderer. It wraps IPC calls to prevent direct Node.js access from the browser context.

// src/preload/index.ts — Secure IPC API

Hive Multi-Agent Coordination Layer

The Hive module (src/main/hive.ts) is the architectural centerpiece. It provides persistent, file-based coordination for multiple agents without requiring a running message broker.

Hive Workspace Structure

Each agent receives an isolated directory under <harnessHome>/hive/:

• inbox/ — Incoming messages from other agents
• outbox/ — Outgoing messages queued for routing
• memory/ — Agent-specific persistent state
• identity.json — Agent metadata and configuration

The Hive router drains outbox messages and delivers them to recipient inboxes. This design survives process restarts and enables agent mobility across machines.

Creating Agents Programmatically

import { spawnAgentCore } from './main/index';
import { AGENT_PROVIDER_PRESETS } from '../shared/agentProvider';

// Select a provider (Claude, Codex, Grok, Antigravity, etc.)
const preset = AGENT_PROVIDER_PRESETS.find(p => p.id === 'codex')!;

const opts = {
  name: 'CodeBot-1',
  provider: preset.id,
  cwd: '/path/to/project',
  command: preset.defaultCommand,
  autoMode: true,
};

// Hive auto-creates workspace at <harnessHome>/hive/agents/<id>
spawnAgentCore(opts);

Agent Provider System (src/shared/agentProvider.ts)

The Agent Provider module enables Munder-Difflin's multi-engine architecture. It defines:

• Supported CLI backends and their binaries
• Spawn arguments and environment configuration
• Model selection logic
• Bridge/hook integration points

This abstraction allows mixing Claude, OpenAI Codex, xAI Grok, and custom providers in the same Hive session.

Memory and Knowledge Services

Semantic Memory (src/main/memory.ts)

Provides vector embedding storage for agent conversations and retrieval-augmented generation. Agents query past interactions through semantic similarity rather than exact string matching.

Knowledge Graph (src/main/knowledge.ts)

Optional enterprise knowledge integration allowing agents to query structured domain data. This module exposes a graph API that agents can invoke through their tool catalog.

Governance and Control Modules

Control (src/main/control.ts)

Implements the global pause/steer/halt API. Operators can:

• Freeze all agent activity
• Redirect agent output to specific channels
• Terminate individual or all agents

The HookServer consumes this API for external orchestration.

Circuit Breaker (src/main/breaker.ts)

Enforces cost caps and error-storm protection:

• Tracks cumulative API spend across providers
• Automatically halts agents exceeding budget thresholds
• Exponential backoff for failing providers

Telemetry (src/main/telemetry.ts)

Collects usage metrics and cost data feeding the circuit-breaker decisions. Records per-agent token consumption, latency percentiles, and error rates.

Background Services and Integration

Git Worktree Management (src/main/git.ts)

Isolates agent file operations through Git worktrees. Each agent receives a lightweight checkout, enabling:

• Concurrent editing without merge conflicts
• Automatic cleanup after agent termination
• Status queries for UI display

External Integrations

Slack bridge (src/main/slack.ts) and webhook handler (src/main/webhook.ts) convert external events into Hive tasks. Messages from Slack channels appear in agent inboxes; agent responses route back to originating channels.

Scheduler and Missions

Background autonomy through periodic jobs:

import { writeConfig } from '../main/config';

writeConfig({
  missions: [
    {
      id: 'heartbeat',
      kind: 'heartbeat',
      label: 'Floor heartbeat',
      intervalMs: 5 * 60_000,
      enabled: true,
      lastFiredAt: Date.now(),
    },
  ],
});

Related files include src/main/triggerHistory.ts and src/main/realtime.ts for event-driven execution.

Shared Utilities (src/shared/)

Cross-cutting code used by both main and renderer:

• triggers.ts — Context-trigger rules (auto-compact, auto-clear)
• toolCatalog.ts — Available agent capabilities registry
• releaseNotes.ts — Version changelog generation

Renderer-to-Hive Communication Pattern

The preload bridge enables secure data flow:

// In a renderer component
window.api.invoke('hive:readInbox', { agentId: 'agent-123' })
  .then(messages => {
    // Preload has already redacted sensitive fields
    setInbox(messages);
  });

This pattern keeps the renderer untrusted while providing full Hive functionality.

Module Interaction Diagram

┌─────────────────┐     IPC      ┌─────────────────┐
│   src/renderer  │◄────────────►│  src/preload    │
│   (React + Vite)│              │  (secure bridge) │
└─────────────────┘              └────────┬────────┘
                                          │
                              ┌───────────▼───────────┐
                              │     src/main/index    │
                              │   (orchestration hub) │
                              └───────────┬───────────┘
            ┌─────────────┬──────────────┼──────────────┬─────────────┐
            ▼             ▼              ▼              ▼             ▼
      src/main/hive   src/main/    src/main/      src/main/    src/main/
      (coordination)  memory.ts    control.ts     git.ts       slack.ts
            │         knowledge.ts breaker.ts
            │
            ▼
    <harnessHome>/hive/
    (persistent agent workspaces)

Summary

• Main process (src/main/) contains core orchestration, Hive management, and all system services
• Renderer process (src/renderer/) provides the React-based interactive UI
• Hive module (src/main/hive.ts) enables persistent file-based multi-agent coordination
• Agent Provider (src/shared/agentProvider.ts) abstracts CLI backends for multi-engine support
• Memory and Knowledge services (src/main/memory.ts, src/main/knowledge.ts) provide semantic retrieval
• Control and Circuit-Breaker (src/main/control.ts, src/main/breaker.ts) enforce runtime governance
• Preload scripts (src/preload/) secure the renderer-main boundary

Frequently Asked Questions

What is the Hive in Munder-Difflin?

The Hive is a file-based coordination system implemented in src/main/hive.ts where agents communicate through dedicated inbox/outbox directories rather than in-memory queues. This design ensures persistence across crashes and enables distributed agent deployment.

How does Munder-Difflin support multiple AI providers?

The Agent Provider module (src/shared/agentProvider.ts) defines preset configurations for Claude, Codex, Grok, Antigravity, and extensible custom providers. Each preset specifies spawn commands, model parameters, and bridge behavior, allowing mixed-provider agent teams.

Can I extend Munder-Difflin with custom UI components?

Yes. The renderer process (src/renderer/src/) uses standard React patterns. New components can import window.api from the preload bridge to interact with the Hive. The existing AgentStrip and MemoryPanel components demonstrate the pattern for displaying agent state.

What protects against runaway agent costs?

The Circuit Breaker (src/main/breaker.ts) tracks per-provider spending and halts agents exceeding configured thresholds. It integrates with Telemetry (src/main/telemetry.ts) for real-time cost accounting and implements exponential backoff for error storms.

Where is agent data stored permanently?

All Hive data resides under <harnessHome>/hive/ on disk, with per-agent subdirectories containing inbox, outbox, memory, and identity files. This location is configurable through src/main/config.ts and survives application restarts.

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