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

> Set up Munder-Difflin locally with our complete installation guide. Follow simple steps to install Node, clone the repo, and run dev for your multi-agent desktop environment.

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

---

**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](https://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

```bash
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:

```bash
npm install

```

### 3. Launch the Development Build

```bash
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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)](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/preload/index.ts).

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

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

```

### Send Inter‑Agent Messages

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

```

### Query Semantic Memory

```ts
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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/router.ts)) and memory wrapper ([`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts)).

## Key Source Files to Explore

| File | Role |
|------|------|
| [`package.json`](https://github.com/chaitanyagiri/munder-difflin/blob/main/package.json) | Project metadata and build scripts |
| [`electron.vite.config.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/electron.vite.config.ts) | Electron‑Vite configuration |
| [`src/main/pty.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pty.ts) | `PtyManager` — native terminal spawning |
| [`src/main/hive.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hive.ts) | On‑disk multi‑agent system |
| [`src/main/hooks.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/hooks.ts) | Provider‑specific hook servers |
| [`src/main/memory.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/memory.ts) | Semantic memory CLI wrapper |
| [`src/preload/index.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/preload/index.ts) | Typed `window.cth` bridge API |
| [`src/renderer/src/components/OfficeFloor.tsx`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/renderer/src/components/OfficeFloor.tsx) | Pixi.js rendering logic |
| [`src/renderer/src/components/TerminalPanel.tsx`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/renderer/src/components/TerminalPanel.tsx) | xterm.js terminal views |
| [`HIVE.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/HIVE.md) | Full design documentation |
| [`SPEC.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/SPEC.md) | Terminal/event plane specification |
| [`DESIGN.md`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/src/main/pty.ts) and provider hooks in [`src/main/hooks.ts`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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`](https://github.com/chaitanyagiri/munder-difflin/blob/main/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.