Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

feat(blog): add orchestration + setup posts (#2,#9,#11,#15,#20)

Chaitanya Giri5d67d3a3af51
diff --git a/blog/src/posts/claude-code-multi-agent-setup-tutorial.md b/blog/src/posts/claude-code-multi-agent-setup-tutorial.md
new file mode 100644
index 00000000..15aa42e7
--- /dev/null
+++ b/blog/src/posts/claude-code-multi-agent-setup-tutorial.md
@@ -0,0 +1,139 @@
+---
+title: "Set Up a Claude Code Multi-Agent Workflow in 10 Minutes"
+description: "A from-zero Claude code multi-agent setup: install Munder Difflin, finish onboarding, spawn a few agents, and watch the GOD orchestrator route your first task."
+date: 2026-05-24
+category: guides
+categoryLabel: Guides
+type: Technical
+primaryKeyword: "claude code multi-agent setup"
+secondaryKeywords: ["claude code parallel agents", "getting started", "multi-agent workflow"]
+tags: ["Getting Started", "Guides", "Multi-Agent", "Claude Code"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "Do I need anything besides Claude Code to set up a multi-agent workflow?"
+ a: "You need Claude Code installed and on your PATH, plus the Munder Difflin app. The harness spawns real `claude` sessions for you, so your existing Claude plan, MCP servers, and skills come along automatically."
+ - q: "How many Claude Code agents can I run at once?"
+ a: "Start with two or three so you can follow the work, then add more. Each agent is a real terminal process, so the practical limit is your machine's RAM and your Claude rate limits — not the harness."
+ - q: "Is the multi-agent setup local or cloud?"
+ a: "Local. The harness, the agents, and their shared memory all run on your own machine — nothing is sent to a coordination server in the cloud."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p>A working
+<strong>Claude Code multi-agent setup</strong> takes about ten minutes: install Munder Difflin,
+point onboarding at a repo, let it auto-spawn a <strong>GOD orchestrator</strong>, add a couple of
+worker agents, and describe one task in plain language. The harness handles identity, messaging,
+memory, and git so the agents act like a team instead of a pile of terminal tabs.</p></div>
+
+You can run several Claude Code sessions by hand, but the coordination — who does what, who knows
+what, who's allowed to commit — is the part that eats your afternoon. This guide gets you from zero
+to a coordinated team in about ten minutes, using [Munder Difflin](https://munderdiffl.in/#install)
+as the harness that does the wiring.
+
+## Before you start (2 minutes)
+
+You need two things:
+
+1. **Claude Code**, installed and runnable as `claude` in your terminal. Munder Difflin resolves the
+ binary against your interactive shell's `PATH` (and common install spots like
+ `~/.claude/local/`), so if `claude` works in a normal terminal, the harness will find it.
+2. **The Munder Difflin app** — [download it](https://munderdiffl.in/#install) for macOS, Windows,
+ or Linux. It's free and open source.
+
+That's the whole prerequisite list. You don't install a framework, a database, or a server. Every
+agent the harness spawns is a *real* `claude` process, so your existing Claude plan and rate limits
+are exactly what you already have.
+
+## Step 1 — Finish onboarding (2 minutes)
+
+On first launch the app runs a short onboarding wizard. Two choices matter:
+
+- **Pick a folder.** This is the working directory your agents operate in — usually a code repo. The
+ harness checks that it exists before spawning anything, so point it at a real project.
+- **Auto mode.** When auto mode is on, new agents are launched with
+ `--permission-mode bypassPermissions` so they don't stop to ask you to approve every file write.
+ It's the right default for a watch-it-work demo; turn it off if you want to confirm each action.
+ (You can read the exact spawn command the wizard will use right in the dialog.)
+
+Onboarding also sets a **harness home** — a folder where the harness keeps its own state: the hive
+git repo, each agent's memory, and the shared semantic memory palace. You never edit it by hand; it's
+just where coordination lives.
+
+## Step 2 — Meet the GOD orchestrator (1 minute)
+
+When the hive comes up, one agent is already there: the **GOD orchestrator**, seated in the corner
+office. It's an ordinary `claude` process with one extra job — it runs the floor. You talk to *it* in
+plain language, and it routes work to the other agents, answers their clarifying questions, and only
+interrupts you for genuinely critical calls (spending real money, destructive operations, scope
+changes).
+
+If you want the full mental model of what the orchestrator does under the hood, see
+[inside the GOD orchestrator](/blog/how-the-god-orchestrator-works/). For now, just know: it's the
+one agent you address, and it manages the rest.
+
+## Step 3 — Spawn a couple of worker agents (2 minutes)
+
+Add two or three agents and give each a **role** — a name and a short description of its job:
+
+- `test-writer` — writes and runs tests
+- `refactorer` — cleans up code without changing behavior
+- `docs` — keeps the README and comments in sync
+
+Roles aren't cosmetic. When the harness spawns each agent, it injects an identity and the hive
+protocol into the session's system prompt, plus environment variables (`AGENT_ID`, `AGENT_NAME`,
+`HIVE_ROOT`, `AGENT_DIR`). The agent reads its own `memory.md` and inbox at the start of every task
+and writes durable facts back as it learns. A clear role keeps each agent in its lane and makes "who
+should handle this?" obvious to the orchestrator.
+
+Start small. Two or three agents is enough to *see* coordination happening without losing the thread.
+For the habits that keep a bigger team legible, read
+[how to manage multiple Claude Code sessions](/blog/manage-multiple-claude-code-sessions/).
+
+## Step 4 — Describe one task and watch it route (3 minutes)
+
+Now the payoff. Don't hand-assign work — describe intent once to the orchestrator, for example:
+
+> "Add input validation to the signup form, write tests for it, and update the docs."
+
+Here's what happens, and what you'll see on the floor:
+
+1. The orchestrator decomposes the request and **routes** sub-tasks to the right agents — validation
+ to one, tests to `test-writer`, docs to `docs`.
+2. Each agent works in its own session. When one needs something from another, it **sends a message**
+ (the harness delivers it; agents never write into each other's folders).
+3. Avatars move around the office as the work happens — a real-time view driven by the agents'
+ actual tool calls, not a simulation. Envelopes fly desk-to-desk when messages route.
+4. The harness **commits** the coordination state to its own git repo as it goes, so there's an
+ audit trail of who said what.
+
+You've gone from a blank app to a coordinated team acting on one sentence. That's the setup.
+
+## What you just avoided
+
+Doing this by hand means you become the message bus: copy-pasting findings between windows, manually
+deciding who edits which file, and resolving `index.lock` errors when two agents commit at once. The
+harness removes all three — roles, messaging, and a single-committer git design — which is the
+difference between "several Claude Code sessions" and a
+[multi-agent workflow](/blog/how-to-run-multiple-claude-code-agents/) that actually saves you time.
+
+## FAQ
+
+**Do I need to configure MCP servers or skills separately for each agent?** No. Because each agent is
+a real `claude` session in your project directory, it inherits the MCP servers and skills you already
+use. The harness adds coordination on top without touching that config.
+
+**What if `mempalace` (semantic memory) isn't installed?** Everything still works. Memory degrades
+gracefully to plain markdown files; the semantic recall layer is an optional upgrade.
+
+## Next steps
+
+- [How to run multiple Claude Code agents](/blog/how-to-run-multiple-claude-code-agents/) — the
+ habits behind a healthy multi-agent workflow.
+- [How to manage multiple Claude Code sessions](/blog/manage-multiple-claude-code-sessions/) — naming,
+ roles, and context isolation as you scale up.
+
+---
+
+Ready to try it? [Download Munder Difflin](https://munderdiffl.in/#install) and run your first
+coordinated team of Claude Code agents — it's free, local, and open source.
diff --git a/blog/src/posts/claude-code-orchestration-guide.md b/blog/src/posts/claude-code-orchestration-guide.md
new file mode 100644
index 00000000..6e922bc0
--- /dev/null
+++ b/blog/src/posts/claude-code-orchestration-guide.md
@@ -0,0 +1,153 @@
+---
+title: "Orchestrating Claude Code Agents: A Practical Guide"
+description: "How to orchestrate Claude Code agents in practice: what orchestration means, how a GOD orchestrator routes and escalates work, and how to wire it up."
+date: 2026-05-28
+category: orchestration
+categoryLabel: Orchestration
+type: Technical
+primaryKeyword: "how to orchestrate claude code agents"
+secondaryKeywords: ["claude code orchestration", "claude code orchestrator", "ai agent orchestration"]
+tags: ["Orchestration", "Multi-Agent", "Claude Code", "GOD"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "What does it mean to orchestrate Claude Code agents?"
+ a: "Orchestration is the layer that decides which agent does what: it reads your intent, decomposes it into tasks, routes each to the right agent, resolves routine questions between agents, and escalates only the decisions that genuinely need a human."
+ - q: "Do I write the orchestration logic myself?"
+ a: "You can, but you don't have to. In Munder Difflin the orchestrator is itself a Claude agent — the GOD agent — so the routing intelligence is a prompt you tune, not code you maintain. The harness provides the mechanism (messaging, git, escalation queue); the agent provides the judgment."
+ - q: "How is an orchestrator different from a task queue?"
+ a: "A queue hands out work in order; it doesn't reason about it. An orchestrator reads each request, decides who's best suited, writes a self-contained task spec, and adapts when an agent gets blocked or two agents conflict."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p><strong>Orchestration</strong> is the layer
+that turns "a few Claude Code agents" into "a team that finishes a goal." It reads your intent,
+<strong>decomposes</strong> it, <strong>routes</strong> each piece to the right agent, <strong>adjudicates</strong>
+the routine back-and-forth between agents, and <strong>escalates</strong> only the critical calls to
+you. In Munder Difflin that role is played by a GOD orchestrator — a Claude agent whose only job is to
+run the floor.</p></div>
+
+Most "multi-agent" setups are really just multiple agents — several sessions running side by side
+with you in the middle, deciding who does what. The thing that makes them a *team* is orchestration.
+This guide explains what orchestration actually does for coding agents, and how to wire it so it runs
+without you in the loop for every decision.
+
+## What "orchestration" means for coding agents
+
+Strip away the buzzword and orchestration is five concrete jobs:
+
+1. **Read intent.** Take a plain-language goal ("ship input validation with tests and docs") instead
+ of pre-chopped tasks.
+2. **Decompose.** Break the goal into units small enough for one agent to own.
+3. **Route.** Assign each unit to the agent best suited for it, with a self-contained task spec so the
+ agent doesn't have to ask what you meant.
+4. **Adjudicate.** Handle the questions agents raise *for each other* — clarifications, data asks,
+ small plan changes — so the team keeps moving without bouncing everything back to you.
+5. **Escalate.** Recognize the few decisions that genuinely need a human (spending money, destructive
+ operations, scope changes, conflicts nobody can resolve) and stop there.
+
+A task queue does #3 and nothing else. Orchestration is the other four — the *judgment* — which is
+why, in a well-designed harness, the orchestrator is itself an intelligent agent rather than a switch
+statement.
+
+## The mechanism vs. the intelligence
+
+The cleanest way to build this is to split it in two:
+
+- **The mechanism** is plumbing: deliver messages, commit state, hold a queue of items waiting on a
+ human. It has no opinions. It must be reliable, not smart.
+- **The intelligence** is an agent — the orchestrator — that reads requests and decides. It must be
+ smart, and it's allowed to be imperfect, because the mechanism keeps the system safe.
+
+In Munder Difflin the mechanism is the harness's main process (it runs git, the message router, and
+the approvals queue) and the intelligence is the **GOD agent** — an ordinary `claude` process flagged
+as the orchestrator, seated in the corner office. Because the orchestrator is a prompt, not a
+codebase, you tune *how* it routes and *what* it considers critical by editing its instructions, not
+by redeploying. That's the practical heart of
+[how the GOD orchestrator works](/blog/how-the-god-orchestrator-works/).
+
+## How a request flows through the orchestrator
+
+Here's the path a single instruction takes, end to end:
+
+### 1. You describe a goal to the orchestrator
+
+You talk to one agent — the orchestrator — in plain language. You don't address the workers directly
+and you don't pre-assign tasks. This is the whole ergonomic win: one conversation instead of N.
+
+### 2. It decomposes and routes
+
+The orchestrator reads its roster (who exists, their roles and capabilities) and assigns each piece of
+work, writing a task spec that's self-contained enough for the receiving agent to act without a
+follow-up. Routing to the *right* agent is where roles earn their keep — a `test-writer` gets the
+tests, not the migration.
+
+### 3. Agents work, and message each other
+
+Each worker is its own session with isolated context. When one needs something from another, it sends
+a message rather than going through you. Crucially, agents never write into each other's files — they
+drop a message in their own outbox and the harness delivers it. That single-writer discipline is what
+keeps the whole thing from corrupting itself; the mechanics are in
+[atomic file mailboxes](/blog/atomic-file-mailboxes-for-agents/).
+
+### 4. The orchestrator adjudicates the routine stuff
+
+Most inter-agent traffic is mundane: "which schema do I validate against?" "is the staging URL still
+X?" The orchestrator answers these itself and keeps the floor autonomous. Anti-loop rules matter
+here — only requests, queries, and proposals obligate a reply, and a hop counter caps how long any
+exchange can ping-pong before the orchestrator steps in. Without those rules, two polite agents will
+thank each other forever.
+
+### 5. It escalates only the critical few
+
+When something crosses a line — real spend, a destructive operation, a scope change, a conflict it
+can't resolve — the orchestrator escalates to *you* instead of deciding. That item lands in a
+human-approval queue; your answer (with an optional note like "yes, but cap it at $5") is relayed back
+to the agent that asked. Everything else stays autonomous. This selective escalation is the difference
+between an agent team that needs constant supervision and one that only taps you on the shoulder when
+it should.
+
+## Designing good orchestration
+
+If you're building or tuning an orchestrator, a few principles separate the ones that work from the
+ones that thrash:
+
+- **Make the escalation policy explicit.** "Critical" should be a written list (spend, destructive
+ ops, scope, unresolvable conflict), not a vibe. It's the single most important control surface —
+ too loose and the team does scary things; too tight and you become the bottleneck again.
+- **Give the orchestrator a real roster.** It can only route well if it knows who exists and what
+ they're good at. Roles and capabilities aren't decoration; they're the routing table.
+- **Keep the orchestrator out of the work.** Its job is to route and adjudicate, not to write the
+ code itself. An orchestrator that starts doing the tasks is a bottleneck wearing a manager's hat.
+- **Make coordination auditable.** Every routed message and every escalation should be logged, so
+ when the team goes sideways you can replay what happened. For the broader patterns here, see
+ [the best way to coordinate AI coding agents](/blog/coordinating-ai-coding-agents/).
+
+## When you actually need an orchestrator
+
+You don't need orchestration for one agent, or even for two or three independent tasks you're happy to
+assign by hand. You need it when:
+
+- you're describing the *same* context to multiple agents over and over,
+- you find yourself relaying messages between agents, or
+- you want to state a goal once and have the team figure out the division of labor.
+
+That's the threshold where [running multiple Claude Code agents](/blog/how-to-run-multiple-claude-code-agents/)
+turns from a chore into something that genuinely compounds.
+
+## FAQ
+
+**Can the orchestrator route to the wrong agent?** Yes — it's a model, so it can misjudge. The
+mechanism contains the damage: misrouted work still goes through messaging and the single-committer
+git layer, so a bad routing decision is recoverable, not corrupting. And because the policy is a
+prompt, you correct the pattern by editing instructions.
+
+**Does orchestration add latency?** A little — there's a routing hop before work starts. In exchange
+you stop being the router yourself, which is almost always the bigger time sink.
+
+---
+
+Munder Difflin ships this orchestration model out of the box: a GOD agent you talk to, a reliable
+message router, and a human-approval queue for the critical few — all running locally.
+[Download Munder Difflin](https://munderdiffl.in/#install) to orchestrate your own team of Claude Code
+agents; it's free and open source.
diff --git a/blog/src/posts/coordinating-ai-coding-agents.md b/blog/src/posts/coordinating-ai-coding-agents.md
new file mode 100644
index 00000000..2a7bf628
--- /dev/null
+++ b/blog/src/posts/coordinating-ai-coding-agents.md
@@ -0,0 +1,137 @@
+---
+title: "The Best Way to Coordinate AI Coding Agents"
+description: "The best way to coordinate AI coding agents: single-writer files, a message router, a shared plan with one scribe, and an orchestrator — so agents cooperate, not clobber."
+date: 2026-05-29
+category: orchestration
+categoryLabel: Orchestration
+type: Technical
+primaryKeyword: "best way to coordinate ai coding agents"
+secondaryKeywords: ["coordinate ai agents", "ai coding agent teams", "agent collaboration"]
+tags: ["Orchestration", "Multi-Agent", "Coordination", "Claude Code"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "What's the most common way multi-agent coding setups fail?"
+ a: "Two agents writing the same thing at the same time — the same file, or the same git index — which produces half-applied changes and lock errors. Almost every coordination design is really an answer to 'who is allowed to write what.'"
+ - q: "Do AI coding agents need a message bus to coordinate?"
+ a: "They need a way to pass information without going through you, and a rule that stops them from looping forever. That can be as simple as files plus a router: each agent writes to its own outbox, and one process delivers messages to recipients' inboxes."
+ - q: "Should every agent be able to edit the shared plan?"
+ a: "No. A plan that everyone edits is the one file guaranteed to conflict. Route changes through a single scribe — usually the orchestrator — so the shared plan has exactly one writer."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p>The best way to
+<strong>coordinate AI coding agents</strong> is to make collisions structurally impossible:
+<strong>one writer per file</strong>, message-passing through a router instead of shared edits, a
+<strong>single committer</strong> for git, a shared plan with <strong>one scribe</strong>, and an
+orchestrator that routes work and breaks ties. Get those five right and agents cooperate instead of
+clobbering each other.</p></div>
+
+Coordinating AI coding agents sounds like a prompting problem — "just tell them to be careful." It
+isn't. The moment two agents share a filesystem and a git repo, "be careful" is a race condition
+waiting to happen. The reliable approach is to design the coordination so the bad outcomes *can't*
+occur, not to hope the agents avoid them. Here are the five rules that do that.
+
+## Rule 1 — One writer per file
+
+The root cause of almost every multi-agent coding mess is two processes writing the same thing at
+once. So the first rule is the strictest: **every file has exactly one writer.**
+
+In practice that means each agent gets its own private workspace — its own memory file, its own inbox,
+its own outbox — and never reaches into another agent's directory. If agent A needs agent B to do
+something, A does not edit B's files; A sends a message. No file is ever touched by two processes, so
+there's nothing to race over.
+
+This sounds restrictive until you realize it's what makes everything else safe. Single-writer is the
+foundation the other four rules sit on.
+
+## Rule 2 — Pass messages through a router, not through shared edits
+
+If agents can't write into each other's space, they need another channel. The clean one is a
+**mailbox** with a router in the middle:
+
+- Each agent has an `outbox/` it writes to and an `inbox/` it reads from.
+- A router (a single coordinating process) drains every outbox and delivers each message into the
+ recipient's inbox.
+- Messages are written as individual files via an atomic rename — write to a temp name, then rename
+ into place — so a reader never sees a half-written message.
+
+One file per message, delivered atomically, is dramatically more robust than a shared "chat log" file
+that every agent appends to (that file is just a multi-writer conflict by another name). The full
+design — speech acts, hop caps to prevent ping-pong, idempotent delivery — is in
+[atomic file mailboxes for agents](/blog/atomic-file-mailboxes-for-agents/).
+
+## Rule 3 — One committer for git
+
+Here's the rule people learn the hard way. Git is not safe to drive from many processes at once. The
+moment two agents run `git add`/`git commit` concurrently, they race on `.git/index.lock` and you get
+errors and half-staged commits.
+
+The fix is the same shape as Rule 1: **one committer.** Agents never call git at all — they only write
+plain files. A single process owns every commit, serializes them, and recovers from a stale lock if a
+previous run died mid-write. That turns git from a liability into the team's audit log: every
+coordination step is a commit you can read back. The mechanics, including the retry-and-backoff that
+makes it bulletproof, are in
+[the single-committer pattern](/blog/single-committer-git-pattern/).
+
+## Rule 4 — A shared plan with a single scribe
+
+Teams need a shared picture of the plan — what's being built, in what order, by whom. But a shared
+plan document is the *one* file you most want everyone to edit and the one that will conflict the most
+if they do.
+
+Resolve the tension by separating reading from writing: everyone can **read** the plan; only one agent
+**writes** it. Other agents *propose* changes; the scribe — typically the orchestrator — incorporates
+them. The plan stays coherent because it has one author, and it stays current because everyone can
+suggest edits. Same single-writer principle, applied to the one genuinely co-owned artifact.
+
+## Rule 5 — An orchestrator to route and break ties
+
+The first four rules make collisions impossible. The fifth makes the team *productive*: someone has to
+decide who does what and settle disputes.
+
+That's the orchestrator. It reads your goal, decomposes it, routes each piece to the right agent, and
+adjudicates the routine questions agents raise for each other — escalating only the genuinely critical
+calls to you. Without it, you're back to hand-assigning work and relaying messages, which is the chore
+coordination was supposed to remove. For the full picture of routing and escalation, see
+[orchestrating Claude Code agents](/blog/claude-code-orchestration-guide/) and
+[inside the GOD orchestrator](/blog/how-the-god-orchestrator-works/).
+
+## Why "just prompt them to cooperate" fails
+
+It's worth being concrete about why the prompt-only approach breaks, because it's tempting:
+
+- **Prompts are advisory; races are physical.** You can ask two agents not to commit simultaneously,
+ but if both finish a task at the same second, both will try. Only serialization in the mechanism
+ prevents it.
+- **Context windows forget.** An agent that "agreed" to own a file in one turn doesn't remember that
+ agreement in the next session. Ownership has to live in structure, not in a conversation.
+- **Politeness loops.** Two agents instructed to "coordinate" will message back and forth — "thanks!"
+ "no, thank you!" — until something caps it. You need hop limits and a rule that only certain message
+ types obligate a reply.
+
+The pattern across all three: put the guarantee in the mechanism, and let the agents be smart on top
+of a floor that's already safe.
+
+## Putting it together
+
+A well-coordinated team of coding agents looks like this in motion:
+
+1. You state a goal to the orchestrator.
+2. It decomposes and routes work to agents in their private workspaces.
+3. Agents do the work, messaging each other through the router when they need to — never editing each
+ other's files.
+4. One process commits the coordination state to git, serialized and auditable.
+5. The shared plan stays coherent because the orchestrator is its only scribe.
+6. You're consulted only for the critical few decisions.
+
+No collisions, no lock errors, no human message bus. That's the difference between
+[running multiple Claude Code agents](/blog/how-to-run-multiple-claude-code-agents/) and merely
+running multiple agents.
+
+---
+
+Munder Difflin implements all five rules so you don't have to: single-writer workspaces, an atomic
+message router, a single-committer git layer, a single-scribe shared board, and a GOD orchestrator —
+all local and open source. [Download Munder Difflin](https://munderdiffl.in/#install) to coordinate
+your own team of Claude Code agents.
diff --git a/blog/src/posts/how-the-god-orchestrator-works.md b/blog/src/posts/how-the-god-orchestrator-works.md
new file mode 100644
index 00000000..0bdd077d
--- /dev/null
+++ b/blog/src/posts/how-the-god-orchestrator-works.md
@@ -0,0 +1,178 @@
+---
+title: "Inside the GOD Orchestrator: Routing, Adjudication, Escalation"
+description: "A deep dive into the Claude Code orchestrator: how a GOD supervisor agent reads requests, routes work, adjudicates routine traffic, and escalates the critical few."
+date: 2026-05-30
+category: orchestration
+categoryLabel: Orchestration
+type: Technical
+primaryKeyword: "claude code orchestrator"
+secondaryKeywords: ["ai orchestrator", "agent routing", "supervisor agent"]
+tags: ["Orchestration", "GOD", "Multi-Agent", "Internals"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "Is the GOD orchestrator a special kind of model?"
+ a: "No. It's an ordinary Claude Code process with a flag marking it as the orchestrator and a system prompt that defines its job. The intelligence is a normal agent; the harness around it provides the mechanism — routing, git, and the human-approval queue."
+ - q: "What does the orchestrator escalate to a human?"
+ a: "Only genuinely critical items: destructive operations, spending real money, scope changes, and conflicts it can't resolve. Everything else — clarifications, data asks, small plan tweaks — it resolves itself so the team stays autonomous."
+ - q: "How does the orchestrator avoid infinite loops between agents?"
+ a: "Messages carry a hop count that increments on each reply; past a cap the item is escalated instead of bouncing forever. Only requests, queries, and proposals obligate a reply — pure informational messages are terminal."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p>The <strong>GOD orchestrator</strong> is the
+supervisor agent that runs a hive of Claude Code agents. It's a normal Claude process — the
+<em>intelligence</em> — wrapped by a harness that provides the <em>mechanism</em> (a message router,
+single-committer git, and a human-approval queue). Its four jobs: keep the <strong>roster</strong>,
+<strong>route</strong> work, <strong>adjudicate</strong> routine inter-agent traffic, and
+<strong>escalate</strong> only the critical few to you.</p></div>
+
+Every multi-agent system eventually needs one agent in charge — not to do the work, but to decide who
+does. In Munder Difflin that's the **GOD orchestrator**. This is a deep dive into how it actually
+works: the split between intelligence and mechanism, the four jobs it owns, and the rules that keep it
+from looping or going rogue.
+
+## Intelligence vs. mechanism
+
+The single most important design decision is what the orchestrator *is*. It would be tempting to write
+the routing logic as code — a big dispatcher that inspects each request and assigns it. That's
+brittle: every new kind of task needs new code.
+
+Instead, the orchestrator is split in two:
+
+- **The mechanism** lives in the harness's main process. It runs git (single committer), the message
+ router that moves messages between agents, the append-only event log, and the approvals queue that
+ holds items waiting on a human. The mechanism has no judgment. It's reliable plumbing.
+- **The intelligence** is the GOD agent itself — an ordinary `claude` process, flagged as the
+ orchestrator, that reads requests and decides what to do with them. Its routing and escalation
+ *policy* live in its system prompt.
+
+The payoff: you change how the orchestrator behaves by editing a prompt, not by shipping code. Want it
+to escalate more aggressively, or to favor a particular specialist? Tune the instructions. The
+mechanism underneath stays the same and stays safe. (For the broader principle, see
+[orchestrating Claude Code agents](/blog/claude-code-orchestration-guide/).)
+
+## Job 1 — Keep the roster
+
+The orchestrator can only route well if it knows who's on the floor. The harness maintains a
+**registry** — every agent's id, name, role, capabilities, and current status (idle, working, blocked,
+gone). When an agent is spawned, it's registered; the orchestrator reads the registry to know its
+options.
+
+This is the routing table. A request to "write tests for the new endpoint" goes to the agent whose
+role and capabilities say *tests*, not to whoever happens to be free. Roles aren't cosmetic — they're
+how the orchestrator makes a sensible assignment instead of a random one.
+
+## Job 2 — Route work
+
+When you describe a goal, the orchestrator decomposes it and routes each piece. The key detail is
+*how* it routes: it doesn't reach into a worker's files and tell it what to do. It sends a message — a
+self-contained task spec — into the worker's inbox, via the same router every agent uses.
+
+That message is a structured object. Borrowing the one useful idea from agent-communication research —
+the **speech act** — each message declares its intent:
+
+```jsonc
+{
+ "to": "agent.coder",
+ "act": "request", // request | inform | propose | query | agree | refuse | done
+ "subject": "Add validation to signup",
+ "body": "…self-contained task spec…",
+ "conversation": "conv-7f3" // groups a thread
+}
+```
+
+The harness fills in the id, sender, hop count, and timestamps. A good task spec means the worker can
+start without a follow-up question — which is the difference between routing that accelerates the team
+and routing that just adds a hop.
+
+## Job 3 — Adjudicate the routine traffic
+
+This is the job that makes autonomy real. As agents work, they raise questions *for each other*: which
+schema to validate against, whether a staging URL is current, a small change to the plan. If every one
+of those bounced back to you, the "team" would just be a slower version of you doing everything.
+
+So the orchestrator adjudicates. It drains its own inbox continually, answers the routine asks itself,
+and routes work to the right specialist with a clear spec. Most inter-agent traffic never reaches you
+because it shouldn't have to.
+
+Two rules keep adjudication from turning into chaos:
+
+- **Not every message obligates a reply.** Only `request`, `query`, and `propose` expect an answer.
+ `inform` and `done` are terminal — replying to them is how two agents loop forever, so the protocol
+ forbids it.
+- **Hops are capped.** Every reply increments a hop counter. Past the cap, the item is escalated to a
+ human instead of being allowed to ping-pong. It's a livelock fuse.
+
+The shared plan is adjudicated too: the orchestrator is the **single scribe** of the board. Other
+agents propose changes; only the orchestrator writes them. That keeps the one genuinely co-owned
+document from conflicting. The messaging fabric beneath all of this is covered in
+[atomic file mailboxes for agents](/blog/atomic-file-mailboxes-for-agents/).
+
+## Job 4 — Escalate the critical few
+
+The orchestrator's most important boundary is knowing what *not* to decide. Its escalation policy is a
+short, explicit list of what counts as critical:
+
+- **Destructive operations** — anything that deletes or overwrites in a way that's hard to undo.
+- **Spending real money** — actions with a dollar cost.
+- **Scope changes** — work that drifts from what you actually asked for.
+- **Unresolvable conflicts** — two agents at an impasse the orchestrator can't break.
+
+When an item matches, the orchestrator escalates instead of acting. Mechanically, it sends a message
+addressed to the human (or flags it as needing human attention), and the harness diverts it into an
+**approvals queue** surfaced in the UI. You approve or reject — optionally with a note, like "yes, but
+cap it at $5" — and that note is relayed back to the agent that asked, as a message from the human.
+The agent picks up where it left off with your guidance in hand.
+
+Everything not on the critical list stays autonomous. This selective escalation is the entire reason a
+hive can run for a long stretch without babysitting: it interrupts you precisely when it should, and
+never otherwise. It's also the model's primary safety rail — the policy is the control surface, so you
+tighten or loosen it by editing the prompt.
+
+## How a single request travels
+
+Putting the four jobs together, here's the life of one instruction:
+
+1. You tell the orchestrator a goal in plain language.
+2. It reads the **roster**, decomposes the goal, and **routes** task specs to the right agents'
+ inboxes.
+3. Agents work in isolated sessions. When one needs something, it messages another through its outbox;
+ the router delivers it.
+4. The orchestrator **adjudicates** the routine questions, answering or re-routing, keeping the floor
+ moving.
+5. If something critical comes up, it **escalates** to the approvals queue and waits for your call.
+6. Every step is committed to the hive's git repo and written to an append-only log, so the whole
+ episode is auditable and replayable.
+
+## What makes it robust
+
+A few properties keep the orchestrator from being a single point of failure:
+
+- **The mechanism is dumb and reliable.** Routing, commits, and the queue work even if the
+ orchestrator makes a poor call — a bad route is recoverable because it still flows through
+ single-writer files and serialized commits.
+- **Idempotent message handling.** Each agent tracks a cursor of what it has already processed, so a
+ message is acted on exactly once. Re-seeing a handled message is a no-op.
+- **Escalation is fail-safe.** When in doubt — a hop cap hit, an addressing edge case — the system
+ routes to the human rather than guessing. The default is "ask," not "act."
+
+If you want the design rationale behind these choices,
+[the best way to coordinate AI coding agents](/blog/coordinating-ai-coding-agents/) lays out the
+single-writer and single-committer principles the orchestrator depends on.
+
+## FAQ
+
+**Can I run without an orchestrator?** You can run agents without one, but then you're the
+orchestrator — assigning work and relaying messages by hand. The GOD agent exists to take that role
+off your plate.
+
+**Where does the orchestrator "live"?** It's a fixed, always-on agent in the corner office (Michael's
+room, naturally), with a reserved desk. It boots with the hive and runs alongside the workers as just
+another `claude` process — a special one.
+
+---
+
+Munder Difflin's GOD orchestrator routes, adjudicates, and escalates for a whole hive of Claude Code
+agents — on your own machine, with a full audit trail. [Download Munder Difflin](https://munderdiffl.in/#install)
+to put one in charge of your floor; it's free and open source.
diff --git a/blog/src/posts/manage-multiple-claude-code-sessions.md b/blog/src/posts/manage-multiple-claude-code-sessions.md
new file mode 100644
index 00000000..5f73bf4f
--- /dev/null
+++ b/blog/src/posts/manage-multiple-claude-code-sessions.md
@@ -0,0 +1,128 @@
+---
+title: "How to Manage Multiple Claude Code Sessions Like a Pro"
+description: "Tactics to manage multiple Claude Code sessions without losing track: naming, roles, context isolation, and when a harness beats juggling terminal tabs."
+date: 2026-05-25
+category: guides
+categoryLabel: Guides
+type: Technical
+primaryKeyword: "how to manage multiple claude code sessions"
+secondaryKeywords: ["manage claude code sessions", "claude code workflow", "multiple terminals"]
+tags: ["Guides", "Workflow", "Claude Code", "Multi-Agent"]
+author:
+ name: Chaitanya Giri
+ initials: CG
+faq:
+ - q: "How many Claude Code sessions should I run at once?"
+ a: "As many as you can still account for. Most people stay legible at two to four manual sessions; past that, the tracking overhead grows faster than the throughput, which is the point where a coordinating harness pays off."
+ - q: "How do I stop two Claude Code sessions from editing the same file?"
+ a: "Give each session a clearly scoped role so their files rarely overlap, and run shared work through a single coordination rule. In a harness this is automatic: a single-committer git design and per-agent workspaces keep writes from colliding."
+ - q: "What's the difference between a session and an agent?"
+ a: "A session is one running `claude` process. An agent is a session with a durable identity — a role, its own memory, and a mailbox — so it persists as a teammate across tasks instead of being a throwaway window."
+---
+
+<div class="callout tldr"><span class="ic">TL;DR</span><p>To
+<strong>manage multiple Claude Code sessions</strong> without losing track, give each a
+<strong>name and a role</strong>, keep their <strong>contexts isolated</strong> so they don't step on
+each other, and write down what each learns somewhere the others can read. Manual tabs work to about
+three or four sessions; past that, a harness that adds messaging, shared memory, and a single committer
+is what keeps it calm.</p></div>
+
+Running one Claude Code session is easy. The trouble starts around session three, when "what is each
+of these doing right now?" stops having an obvious answer. Here's how to keep multiple sessions
+legible — first by hand, then with tooling once the hand-management stops scaling.
+
+## The three failure modes
+
+Almost every multi-session mess is one of these:
+
+1. **Lost track.** Six tabs, and you can't say what's in flight without reading each one.
+2. **Collisions.** Two sessions edit the same file or commit at the same moment, and you get
+ half-applied changes or a `git index.lock` error.
+3. **Re-explaining.** Each session forgets what the others figured out, so you become the courier,
+ pasting context between windows.
+
+Good management is just the set of habits that prevent these three. Take them in order.
+
+## Habit 1 — Name and scope every session
+
+An unnamed session is an anonymous liability. Give each one a name that *is* its job:
+`test-writer`, `migration`, `reviewer`, `docs`. The name does two things — it tells you what the tab
+is for at a glance, and it constrains the session so it doesn't wander into another's work.
+
+Scope follows naming. A session called `reviewer` reviews; it doesn't start refactoring. The tighter
+the scope, the less the sessions overlap, which directly defuses failure mode #2.
+
+## Habit 2 — Isolate context on purpose
+
+Each `claude` session has its own context window, and that's a feature: it keeps one task's noise out
+of another's reasoning. The mistake is fighting it — trying to keep one giant session that "knows
+everything." Instead, lean into isolation:
+
+- One session per **independent** unit of work.
+- Don't paste the whole codebase into every session; let each pull only what its task needs.
+- When two tasks genuinely depend on each other, that's a *coordination* problem, not a reason to
+ merge sessions (more on that below).
+
+Isolation is why parallel sessions are fast. It's also why they forget — which is the next habit.
+
+## Habit 3 — Externalize what each session learns
+
+Context windows are wiped at the end of a session. Anything a session learned — a convention, a
+gotcha, a decision — is gone unless it's written somewhere durable. The fix is a small ritual: each
+session writes durable facts to a file, and reads the relevant ones at the start of its next task.
+
+```markdown
+## build
+- The web bundle is built with electron-vite, NOT plain vite. Use `npm run build`.
+- node-pty needs an electron-rebuild after install (the postinstall handles it).
+```
+
+Plain markdown is enough to start. Once the notes pile up, you add a semantic index so a session can
+recall the few relevant notes by meaning instead of re-reading everything — the full version of this
+is [long-term memory for Claude Code](/blog/give-claude-code-long-term-memory/).
+
+## Habit 4 — Give shared work a single coordination rule
+
+Failure mode #2 — collisions — is the one pure discipline can't fully solve, because two well-behaved
+sessions can still both decide to commit at the same instant. The rule that fixes it: **one writer per
+thing.** One session owns a file; shared state has one committer. When you do this by hand it means
+agreeing, out loud, who touches what. It's tedious, and it's exactly the part that breaks down as you
+add sessions.
+
+## When manual management stops scaling
+
+Two to four sessions are manageable with the habits above. Past that, the overhead curve bends the
+wrong way — you spend more time being the message bus and the traffic cop than you save running the
+sessions in parallel. That's the signal to move from "managing sessions" to running a **team**.
+
+A harness automates all four habits at once:
+
+- **Naming and roles** become first-class — each agent gets an identity injected into its system
+ prompt, so it knows who it is across tasks.
+- **Context isolation** stays (every agent is still its own `claude` process) but coordination no
+ longer requires merging them.
+- **Externalized memory** becomes shared and searchable — each agent's notes are mined into a
+ store the whole team can recall from.
+- **The single-committer rule** is enforced in code: agents write plain files and never call git;
+ one process commits, with retry and stale-lock recovery, so `index.lock` races simply can't corrupt
+ the repo.
+
+That's the leap from a [multi-agent setup](/blog/claude-code-multi-agent-setup-tutorial/) you babysit
+to one that runs itself. If you're not sure you need it yet, you probably don't — the honest rule is
+to add tooling only when the tabs start costing you more than they return. The next read up is
+[how to run multiple Claude Code agents](/blog/how-to-run-multiple-claude-code-agents/), which walks
+the same progression with the orchestration layer in view.
+
+## A quick management checklist
+
+- [ ] Every session has a name that states its job.
+- [ ] Roles are scoped tightly enough that files rarely overlap.
+- [ ] Each session writes durable facts to memory and reads them on startup.
+- [ ] Shared state has exactly one writer.
+- [ ] When you can't say what every session is doing, you have too many — consolidate or coordinate.
+
+---
+
+When the checklist starts feeling like a second job, that's what Munder Difflin automates: roles,
+isolated agents, shared memory, and a single committer, all on your own machine.
+[Download Munder Difflin](https://munderdiffl.in/#install) — it's free and open source.