How to Set Up Munder‑Difflin Locally: A Complete Installation Guide for the Multi‑Agent Desktop Environment

You can set up Munder‑Difflin locally by installing Node 18+, a C/C++ toolchain for native modules, cloning the repository, running npm install, and launching with npm run dev.

Munder‑Difflin is an Electron‑based desktop application that transforms terminal‑agent CLIs like Claude Code, Antigravity, Codex, and Grok into autonomous agents inhabiting a shared 2‑D office floor. This guide covers how to set up Munder‑Difflin locally, from prerequisites to your first multi‑agent session.

Prerequisites for Local Setup

Before you begin, ensure your system meets these requirements:

• Node.js ≥ 18 with npm (download from nodejs.org)
• C/C++ toolchain for building the node‑pty native addon:
  • macOS: xcode-select --install
  • Windows: Visual Studio Build Tools
  • Linux: build-essential or equivalent
• At least one agent CLI on your PATH (e.g., claude for Claude Code)
• Optional: API keys and local LLM configurations (set via Settings → AI Engines after first launch)

Step‑by‑Step Installation

1. Clone the Repository

git clone https://github.com/chaitanyagiri/munder-difflin.git
cd munder-difflin

2. Install Dependencies

The postinstall hook automatically rebuilds node‑pty for the current Electron ABI:

npm install

3. Launch the Development Build

npm run dev

This starts the app with hot‑reload enabled. On first launch, an onboarding wizard guides you through configuring the "GOD" agent (Michael) and adding your first agent.

Available npm Scripts

Script	Purpose
npm run build	Production build via electron‑vite
npm run preview	Preview the production build locally
npm run typecheck	Run TypeScript checks for Node and web code
npm run dist:*	Create distributable binaries (mac, Windows, Linux)

Troubleshooting Native Module Errors

If you encounter a node‑pty loading error after an Electron upgrade, re‑run npm install. The postinstall script at package.json line 18 automatically executes electron‑rebuild against the current Electron ABI.

Core Architecture Overview

Understanding how to set up Munder‑Difflin locally requires familiarity with its dual‑plane architecture:

Terminal Plane (src/main/pty.ts)

The PtyManager class spawns each CLI in a native PTY using node‑pty and streams I/O over IPC. The renderer communicates with the main process exclusively through the typed window.cth bridge defined in [src/preload/index.ts](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/preload/index.ts).

Hive / Event Plane (src/main/hive.ts)

The on‑disk multi‑agent layer manages:

• Per‑agent memory and mailboxes
• A shared blackboard for coordination
• An event log for audit trails

A router delivers messages while the "GOD" agent (Michael) adjudicates, assigns work, and escalates critical actions to the human user.

The UI renders this world with Pixi.js for the office floor and xterm.js for terminal streams, letting you watch avatars walk, envelopes fly, and live terminal output simultaneously.

Code Examples for Local Development

Once you set up Munder‑Difflin locally, use these patterns from the preload bridge:

Spawn a New Agent

// From the renderer (React)
window.cth.agent.spawn({
  provider: 'claude',
  name: 'Claude-Agent-01',
  workDir: '~/projects/my-app',
});

Send Inter‑Agent Messages

window.cth.router.send({
  from: 'Claude-Agent-01',
  to: 'Codex-Agent-02',
  payload: 'Please review the latest PR.',
});

Query Semantic Memory

const results = await window.cth.memory.search('how to use react hooks');
console.log(results);

All IPC calls flow through the hive's router (src/main/router.ts) and memory wrapper (src/main/memory.ts).

Key Source Files to Explore

File	Role
package.json	Project metadata and build scripts
electron.vite.config.ts	Electron‑Vite configuration
src/main/pty.ts	PtyManager — native terminal spawning
src/main/hive.ts	On‑disk multi‑agent system
src/main/hooks.ts	Provider‑specific hook servers
src/main/memory.ts	Semantic memory CLI wrapper
src/preload/index.ts	Typed window.cth bridge API
src/renderer/src/components/OfficeFloor.tsx	Pixi.js rendering logic
src/renderer/src/components/TerminalPanel.tsx	xterm.js terminal views
HIVE.md	Full design documentation
SPEC.md	Terminal/event plane specification
DESIGN.md	Visual design guidelines

Summary

• Node 18+ and a C/C++ toolchain are required to build native dependencies
• Clone, npm install, npm run dev is the complete local setup workflow
• The onboarding wizard configures Michael (GOD agent) on first launch
• Re‑run npm install to fix node‑pty errors after Electron updates
• All renderer‑to‑main communication uses the typed window.cth bridge in src/preload/index.ts

Frequently Asked Questions

What is the minimum Node.js version for Munder‑Difflin?

Node.js 18 or higher is required. The node‑pty native addon and Electron‑Vite build system depend on modern Node APIs. Older versions will fail during npm install or produce ABI mismatch errors at runtime.

Why does Munder‑Difflin need a C/C++ compiler?

The node‑pty native module requires compilation for your specific platform and Electron ABI. This module creates pseudo‑terminal (PTY) processes that host the actual CLI agents. Without the toolchain, the install fails with gyp or node‑api errors.

Can I use Munder‑Difflin without Claude Code?

Yes. The PtyManager in src/main/pty.ts and provider hooks in src/main/hooks.ts support multiple CLIs including Antigravity, Codex, and Grok. You need at least one supported agent on your PATH, but the specific provider is configurable.

Where are agent configurations and memory stored?

The hive layer in src/main/hive.ts maintains an on‑disk directory with per‑agent folders containing memory vectors, mailbox JSON files, and the shared blackboard. This persists across app restarts and is independent of the Electron user data directory.

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