---
> [!NOTE]
> **The world's best agents. The world's worst paper company.**
> Munder Difflin takes the terminal-agent CLIs you already run — `claude`, `agy`, and `codex` — and turns them
> into a self-coordinating team: each agent gets long-term memory, a mailbox, and a desk on a 2D
> office floor — and a **GOD orchestrator agent** routes work between them while you watch.
## What it is
Munder Difflin is a desktop app that wraps **real terminal-agent CLIs** as fully-capable agents,
wires them into a **hive mind**, and puts a **GOD orchestration agent** in charge — the one agent
*you* talk to in order to get things done. Under the hood it runs the **fastest memory layer in the
world** so every agent remembers what it learns and recalls it instantly.
- **Every terminal is an agent.** Each `claude`, `agy`, `codex`, or custom session runs as a real
process in a pseudo-terminal (`node-pty`), byte-for-byte authentic, rendered with xterm.js.
- **Every agent is an avatar.** Sessions appear as characters on a Pixi.js office floor — they walk
to stations as they work, and envelopes fly desk-to-desk when they message each other.
- **The hive coordinates them.** Agents read their memory and drain a mailbox; the router moves
messages between inboxes; the GOD agent adjudicates, assigns, and escalates only when it needs you.
- **Memory that's instant.** A markdown-first memory layer with a semantic recall index means agents
remember across sessions and recall in milliseconds.
## How it works
```
you ── talk to ──► ┌─────────────┐
│ GOD agent │ orchestrator / supervisor
│ (Michael's │ roster · routing · adjudication
│ office) │ blackboard · task ledger
└──────┬──────┘
│ assigns · routes · escalates
┌────────────────────────┼────────────────────────┐
▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐
│ agent A │ message │ agent B │ message │ agent C │
│ provider │ ─────────► │ provider │ ─────────► │ provider │
│ + memory │ │ + memory │ │ + memory │
└───────────┘ └───────────┘ └───────────┘
└──────── shared hive: memory · mailbox · blackboard · log ───────┘
```
1. **You spawn agents** — each is a normal terminal process (`claude`, `agy`, `codex`, or custom)
with its own working directory, identity, and provider-specific lifecycle.
2. **Agents collaborate through the hive** — a local git repo of plain files. They write to their own
`outbox/`; the harness's router delivers into recipients' `inbox/`. No agent ever touches git
(single-committer design avoids `index.lock` corruption).
3. **The GOD agent runs the floor** — it reads every request, resolves routine ones itself (keeping
the system fully autonomous), and only escalates *critical* items (spend, destructive ops, scope
changes) into an approvals queue you act on.
4. **Everything is visible** — you watch avatars move, envelopes fly, and the live terminal stream;
you can type back into any session, browse its files, and read its git history.
See [`HIVE.md`](./HIVE.md) for the full multi-agent design, [`SPEC.md`](./SPEC.md) for the
terminal/event plane, and [`DESIGN.md`](./DESIGN.md) for the visual system.
## Features
| Area | What works today |
|---|---|
| **Real terminals** | Spawn Claude Code, Antigravity (`agy` / Gemini), OpenAI Codex, or a custom command in a `node-pty` PTY. Full read/write/resize/kill, live streaming over IPC, multi-agent. |
| **Multi-provider hive** | Claude Code, Antigravity, and Codex workers can all participate in the same hive. Claude uses native hooks; Antigravity gets a native `agy-hook` bridge; Codex receives the protocol as its initial prompt and participates through inbox/outbox routing. |
| **The hive** | On-disk multi-agent layer: per-agent identity + long-term memory, atomic-file mailboxes, a shared blackboard, append-only event log, single-committer git. |
| **GOD orchestrator** | An always-on supervisor agent that adjudicates traffic, routes tasks, scribes the blackboard, and escalates only critical items to you. |
| **Memory layer** | Markdown-first long-term memory per agent, mined into a shared semantic palace for instant recall; searchable from the UI. Degrades gracefully when the index isn't installed. |
| **Office floor** | Pixi.js scene with a Tiled office map, camera, recolored cast, pathfinding, seat assignment, and tool-bubble overlays. |
| **Message handoffs** | When the hive routes a message, an envelope flies from sender to recipient (tinted by speech-act; escalations fly to the door) and pops an arrival sparkle. |
| **Per-agent panel** | Live terminal, command bar to type back, fullscreen terminal, sandboxed file browser + CodeMirror editor, and a git tab (status, log, commit graph, branches). |
| **Approvals & memory panels** | Human-in-the-loop approval queue for escalations; a memory search panel over the shared palace. |
| **Onboarding wizard** | First-run setup: harness home, registered repos, default command, auto-mode. |
| **Design system** | Fully tokenized SNES / Animal-Crossing aesthetic — pixel panels, buttons, badges, hand-drawn icons. See [`DESIGN.md`](./DESIGN.md). |
| **Command Center** | Michael's control surface: Terminal, Floor (roster + dispatch + per-agent model selector + live fleet monitoring), Memory (MemPalace + text search + memory graph), Activity (log + board + real token telemetry + observability + CI watcher), Tasks (kanban board with dependencies + status tracking), and a dedicated Schedules tab (recurring missions + adaptive heartbeat). |
| **Per-agent git worktrees** | 'Git isolation' toggle in Add Agent auto-provisions a dedicated worktree per agent on spawn and tears it down on kill — agents never collide on branches. |
| **Token & cost telemetry** | Activity tab reads `~/.claude/projects/` JSONL transcripts and surfaces real token counts + estimated USD cost per agent per session, backed by a durable cost ledger that survives restarts. |
| **Per-agent token budgets** | Set a token budget per agent and watch live fleet monitoring track consumption across the whole roster — paired with the cost/runaway circuit breaker to keep spend in check. |
| **Observability** | Live OpenTelemetry collector with per-model cost attribution, a fleet grid, and a per-agent tool-span waterfall — see exactly what every agent is doing and what it costs, in real time. |
| **Context-window gauge** | Each agent card's progress bar is a context-window gauge — see how much of the model's context each agent has consumed at a glance. |
| **Circuit breaker** | A cost/runaway guard with a steer → constrain → stop ladder: the breaker nudges, then constrains, then stops agents that loop, storm errors, or blow their budget. |
| **HITL gate & mid-run control** | Human-in-the-loop gate, mid-run steer, and graceful stop — all driven through Claude Code hook returns, so you can intervene without killing the session. |
| **Durable persistence** | SQLite-backed durable store keeps window bounds + history across restarts, alongside the durable cost ledger and persisted session IDs. |
| **MemoryReflector** | Memory condensation that summarizes and bounds per-agent memory over time, so long-term memory doesn't grow without limit. |
| **Configurable home folder** | Point the hive/memory home at any folder, with a safe move that relocates existing state without losing it. |
| **Restore team** | One-click "Restore team" rebuilds last session's workers after a harness restart — no more re-adding agents by hand. |
| **Shareable hires** | Import a ready-made agent role — provider, model, flags, goal, capabilities, token budget — from a `munderdifflin://hire` deep link or a local manifest file. Import only *pre-fills* the Add-Agent modal (behind an "imported" banner); spawning stays a human click. The manifest is validated as untrusted input (no executable field, a default-deny flag allowlist, an https-only bounded fetch). Browse ready-made roles at [The Hiring Fair](https://munderdiffl.in/hires/). |
| **Task kanban** | Dependency-aware kanban board in the Command Center Tasks tab — assign tasks to agents, track status across todo/doing/blocked/done, wire dependencies so work starts in order. |
| **Scheduled missions & heartbeat** | Recurring auto-dispatch missions with label, interval, target agent, and body — plus a scheduler heartbeat that re-engages the floor when it goes quiet. Missions now live in their own Schedules tab with last/next-fired times. |
| **Terminal work-order handoff** | Providers without an inbox-drain hook receive hive mail as a `WORK ORDER FROM HIVE` typed into their terminal; if the renderer is unavailable, the message bounces to the GOD agent instead of disappearing. |
| **Slack/webhook ingress** | Slack and generic webhook ingress expose local endpoints through tunnelmole, so POSTs pass straight through and failed tunnels surface a real error instead of a silent broken URL. |
| **GitHub ingestion** | Pull open issues from any registered repo via the `gh` CLI and assign them to agents with one click from the Command Center. |
| **CI status watcher** | Live pass/fail/in-progress status for GitHub Actions runs, visible in the Activity tab for every registered repo. |
| **Threaded chat** | Every hive message is grouped by conversation and rendered as a reply chain in each agent's Messages tab — readable, replyable, auditable. |
| **Desktop notifications** | Native OS notifications when an agent finishes a task or is waiting for your input. |
| **Agent archival** | Closing an agent tab archives it (memory + history preserved) rather than destroying it. |
| **Avatar states** | Avatars reflect real work — including new v0.2.0 states for *compacting* (context compaction) and *looping* (circuit-breaker intervention), on top of crisper HiDPI floor text and high-contrast speech bubbles. |
> [!NOTE]
> **Status: v0.2.8 — shareable hires.** The headline: **shareable hires** — package a role-configured agent (provider, model, flags, goal, capabilities, token budget) as a portable `munder-difflin/hire@1` manifest, share it as a file or host it in **[The Hiring Fair](https://munderdiffl.in/hires/)**, and import it into any office with one click. Import only *pre-fills* the Add-Agent modal (the human always clicks spawn), with the manifest validated end to end as untrusted input (no executable field, a default-deny flag allowlist, an https-only bounded fetch with per-hop redirect re-validation). Building on the multi-provider floor — Claude Code, Antigravity (Gemini via `agy`), and OpenAI Codex all work as first-class hive participants (Antigravity via a native `agy-hook` bridge, Codex via lifecycle-hook parity plus protocol injection and provider-agnostic inbox/outbox routing) — v0.2.4→v0.2.7 add: **Free Flow voice dictation** (hold Option to talk; Groq Whisper transcribes straight into the composer), an opt-in **enterprise Knowledge Graph** agents query for ranked passages from your own documents/policies/context, **multi-window "floors"** (isolated offices with per-PTY routing), a **richer message composer** with file & image attachments, **agent session resume** across restarts (with a per-agent *Restart & Continue* button), **drag-a-file-onto-the-terminal** path injection, and **Slack/webhook triggers** that pipe a channel straight into Michael's queue. Everything from v0.2.0–v0.2.3 — observability, circuit breaker, durable persistence, context gauges, Command Center, task kanban, GitHub/CI integration, threaded conversations, desktop notifications, agent archival, and the dedicated Schedules tab — remains functional and shipping. macOS (signed), Windows, and Linux builds are available on the releases page.
## Getting started
### Prerequisites
- **macOS, Windows, or Linux**.
- **Node.js 18+** and npm.
- A **C/C++ toolchain** for `node-pty`'s native addon — on macOS, install Xcode Command Line Tools:
```bash
xcode-select --install
```
- At least one supported terminal-agent CLI on your `PATH`: **[Claude Code](https://claude.com/claude-code)**
(`claude`, the default command), **Antigravity** (`agy`, Gemini), or **OpenAI Codex** (`codex`).
Claude uses native hooks, Antigravity uses the `agy-hook` bridge, and Codex participates through
initial-prompt protocol injection plus inbox/outbox routing.
- *Optional:* the semantic memory index for instant cross-session recall (the app works without it —
markdown memory still functions).
### Install & run
```bash
git clone https://github.com/chaitanyagiri/munder-difflin.git
cd munder-difflin
npm install # postinstall rebuilds node-pty against Electron's ABI
npm run dev # launches the Electron app with hot reload
```
On first launch you'll go through the onboarding wizard, then land on the floor. Use **Add agent** to
spawn your first session — the GOD agent seats itself in Michael's office automatically.
### Other scripts
```bash
npm run build # production build via electron-vite
npm run preview # preview the production build
npm run typecheck # type-check the node (main/preload) and web (renderer) projects
```
> If `node-pty` fails to load after an Electron upgrade, re-run `npm install` (the `postinstall` hook
> runs `electron-rebuild` against the current Electron ABI).
## Architecture
Two data planes feed one renderer:
```
┌───────────────────────────────────────────────────────────────┐
│ Electron Renderer (React) │
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
│ │ Office Floor │ │ Terminal + Command Bar │ │
│ │ (Pixi.js) │ │ Files + Git tabs (xterm.js) │ │
│ └─────────▲────────┘ └────────────▲─────────────────┘ │
│ │ avatar state │ pty bytes / fs / git │
└─────────────┼──────────────────────────┼───────────────────────┘
│ IPC (contextBridge: window.cth)
┌──────┴──────────┐ ┌──────┴─────────────┐
│ Event Plane │ │ Terminal Plane │
│ hooks / hive │ │ node-pty PTYs │
│ router + GOD │ │ + fs + git │
└────────▲────────┘ └──────▲─────────────┘
│ hook payloads │ stdin / stdout
└─────────┬──────────────┘
┌──────┴──────────────┐
│ claude / agy / codex│
└─────────────────────┘
```
- **Terminal plane.** The main process owns a `PtyManager` that spawns each agent as a `node-pty`
process and streams output over per-id IPC (`pty:data:
# Munder Difflin
**Local multi-agent harness for [Claude Code](https://claude.com/claude-code),
Antigravity (Gemini), and OpenAI Codex.**
Autonomous agents that message, route, and remember — coordinated by a **GOD** orchestrator
you talk to, and visualized as avatars at work on a shared office floor.
