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
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.