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

> Explore Munder-Difflin's main modules, including core orchestration, React UI, and multi-agent coordination. Understand the Electron architecture for efficient development.

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

---

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

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

```typescript
// 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.

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

```

## Hive Multi-Agent Coordination Layer

The **Hive module** ([`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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

```typescript
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/slack.ts)) and **webhook handler** ([`src/main/webhook.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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:

```typescript
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/triggerHistory.ts) and [`src/main/realtime.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/realtime.ts) for event-driven execution.

## Shared Utilities (`src/shared/`)

Cross-cutting code used by both main and renderer:

- **[`triggers.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/triggers.ts)** — Context-trigger rules (auto-compact, auto-clear)
- **[`toolCatalog.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/toolCatalog.ts)** — Available agent capabilities registry
- **[`releaseNotes.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/releaseNotes.ts)** — Version changelog generation

## Renderer-to-Hive Communication Pattern

The preload bridge enables secure data flow:

```typescript
// 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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts)) enables persistent file-based multi-agent coordination
- **Agent Provider** ([`src/shared/agentProvider.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/shared/agentProvider.ts)) abstracts CLI backends for multi-engine support
- **Memory and Knowledge** services ([`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts), [`src/main/knowledge.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/knowledge.ts)) provide semantic retrieval
- **Control and Circuit-Breaker** ([`src/main/control.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/control.ts), [`src/main/breaker.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/breaker.ts)) tracks per-provider spending and halts agents exceeding configured thresholds. It integrates with **Telemetry** ([`src/main/telemetry.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/config.ts) and survives application restarts.