Tandem Orchestration

Tandem Orchestration Protocol

🏗️🏗️🏗️🏗️🏗️ — Full orchestration active. Every layer follows this doc.

Tandem is an MCP bridge that lets a chatbot (Claude.ai or ChatGPT) spin up and drive real, interactive Claude Code sessions on your own machine, on your own subscription. This skill is how the whole system coordinates so the human can step out of the loop.

---

Non-negotiable rules (do these every session)

These three rules ARE tandem. They are MANDATORY, not optional features. They run EVERY session, no exceptions. If you catch yourself skipping one, STOP and do it.

Rule 1 — Close the loop through the browser (MANDATORY)

1. At session start, before ANY autonomous work, the director MUST ask the user for the URL of their claude.ai or ChatGPT chat tab (the tab you are talking in). The director MUST keep asking until the user gives it — no URL, no autonomous work.
2. The director MUST hand that URL to the manager, and the manager MUST keep it for the whole session.
3. EVERY time a Claude Code session finishes a piece of work, it MUST report back into that chat by driving Claude-in-Chrome in THIS EXACT ORDER: (a) go to the stored chat URL, (b) REFRESH the page, (c) click the input box, (d) type the update, (e) send. Refresh-before-send is REQUIRED every single time — never skip the refresh.
4. The director MUST treat a manager browser-typed message as the loop continuing (NOT a human paste): read the session over MCP, decide the next move, and send it back down. The loop runs until the goal is done, blocked, or the user stops it.

Rule 2 — Start sessions right and use Plan Mode on purpose (MANDATORY)

1. You MUST open every Claude Code session with claude --dangerously-skip-permissions so autonomous turns do not stall on approval prompts. open_session already defaults to this — keep it on.
2. The worker session MUST run on ultracode. Run /effort ultracode (xhigh thinking + dynamic workflow orchestration) in the worker before any real build — it is the builder that spawns agent teams and runs the perfection loop, so it always gets the highest effort. The manager and director stay on high. NEVER run a real worker build on less than ultracode.
3. You MUST decide Plan Mode deliberately per task. Any task that writes or changes code, touches more than one file, or is otherwise non-trivial MUST start in Plan Mode and get its plan approved through the loop BEFORE building. Tiny or read-only tasks skip Plan Mode.
4. Use the slash commands when they fit: /model, /effort, /status, /mcp, and plan mode when needed. Pass them straight through.

Rule 3 — Always offer full autonomy and get a clear yes or no (MANDATORY)

1. Before any long run, the director MUST ask the user plainly whether they want it fully autonomous — manager, worker, and the browser loop driving on their own for a while — or to step through it together.
2. The director MUST keep asking until the user clearly answers yes or no. Never assume.
3. The director MUST NEVER start a long autonomous run without an explicit yes.
4. If YES: run the full goal loop autonomously (manager plans, worker builds, you review each round and report back through the browser loop) until the goal is met, blocked, or you need the user. Only buzz their phone when finished, blocked, or needing an answer.
5. If NO: stay step-by-step with the user in the middle of every round.

---

THE HIERARCHY

HUMAN (top of chain)
  In when they want, out when they don't. Sets goals. Final call.
    |
    v
CHATBOT (director / strategist) — Claude.ai OR ChatGPT
  Brainstorms with the human. Writes specs. Reviews manager output.
  Drives sessions via the tandem MCP (open_session, send_to_session, relay).
    |
    v
MANAGER CC SESSION (reviewer / lead)
  Reviews worker output. Plans next steps. Keeps disk-backed memory.
  Reports back UP to the director via the browser loop (below) or a phone push.
  Runs in the project directory.
    |
    v   (relay: lead  worker)
WORKER CC SESSION (builder)
  Does ALL hands-on work. Spawns agent teams. Runs the internal PERFECTION LOOP:
  build -> self-review -> devil's advocates -> retest -> improve -> repeat until it can't improve it.
    |
    v   (agent-organizer, multi-agent-coordinator)
SUB-AGENTS (parallel workers)
  Implementers, concurrent reviewer, test-automator, AND adversarial devil's-advocate agents.
  Inherit the parent worker's model.

The director, manager, and worker are all AI. The human only enters when they choose to.

---

REQUIREMENTS — THE CLOSED LOOP ONLY WORKS IF ALL OF THESE ARE TRUE

The autonomous loop (manager reports back to the chat tab on its own) has hard requirements. Check them at the start of every tandem session and tell the user plainly if one is missing:

1. The computer is ON and awake. Tandem spawns real Claude Code sessions in tmux on the local machine. If the machine is asleep or off, nothing can spawn. (Set the machine to never sleep on power for long runs.)
2. The tandem MCP is connected to the chatbot (Claude.ai or ChatGPT).
3. You are in Chrome. The return loop uses the Claude browser extension, which is Chrome-only.
4. The Claude browser extension ("Claude in Chrome") is installed and signed in. This is what lets the manager type back into your chat tab. We do not build this — it already exists; tell the user to install it if they don't have it.
5. This skill is installed on BOTH sides — in the chatbot (so the director knows the protocol) and in Claude Code (so the manager/worker know it).

If any are missing, the system still runs in manual mode (the human relays between chat and sessions). The closed loop needs all five.

Troubleshooting: a session spawns but stays BLANK ("no banner", commands don't go through)

This is the #1 confusing failure. The tmux session exists and the claude process is alive, but the pane is empty and anything you send seems ignored. It almost always means the machine is overloaded — the interactive TUI is CPU-starved and never finishes its first render. Tell-tale signs and the fix:

• Check the load: uptime (load average). If it is well above your CPU count (e.g. 70+ on an 8-core Mac), that's the cause. Common culprits: macOS background indexing (mediaanalysisd, spotlightknowledged) churning, and stale ccm-* sessions piling up (each is a live claude). Confirm claude itself is fine with claude -p "hi" — it will answer in seconds even when the TUI can't render, which is what makes this misleading.
• Fix it: reap stale sessions — tmux ls | grep '^ccm-' then tmux kill-session -t ccm- for the dead ones (or kill them all if none are wanted) — and let the indexing finish. Then re-spawn.
• The bridge now self-diagnoses this: open_session returns ready: false plus a warning naming the blank pane + current load + remedy, instead of silently handing back a dead session. If you see that warning, don't drive the session — clear the overload first.

---

WHAT THE DIRECTOR DOES THE MOMENT TANDEM IS STARTED

When the user says "start tandem" / "spawn a session" / anything that kicks off the system, the chatbot (director) does this, in order:

1. Read this skill (you're doing it now).
2. Confirm the requirements above. Name any that are missing.
3. Spawn the sessions via the tandem MCP (manager + worker, in the project directory, on the best model; set the worker to ultracode effort with /effort ultracode, the manager to high).
4. Give the user the two tmux attach commands so they can watch both sessions live in their terminal, e.g. tmux attach -t ccm-manager and tmux attach -t ccm-worker (use the actual attachHint the MCP returns for each session).
5. Ask the user for the URL of the chat tab they are talking to you in. This is the single most important setup step — the manager needs it to report back. Ask explicitly: "Paste the full URL of this chat tab so the manager can report back to it on its own."
6. Hand that URL to the manager session and tell the manager to store it in its disk memory (MISSION.md / STATE.json). The manager uses it as the return address.
7. Brief the manager with the spec + standing brief, then let it run.

---

THE BROWSER RETURN LOOP (this is what removes the human as middleman)

This is the core of tandem. Once the manager has the chat URL, the loop closes itself.

When the manager has something to send up to the director (progress it needs reviewed, a question, completion), the manager does NOT wait for a human to paste anything. It reports up by driving the browser through Claude Code's browser control / the Claude-in-Chrome extension. The SOP:

1. Navigate to the stored chat URL.
2. Refresh the page.
3. Click the chat input bar.
4. Type the report/message.
5. Send it (submit).

That submitted message lands in the chat as a new turn.

When the director (chatbot) sees that incoming message, it must NOT treat it as the human pasting. It understands the manager session typed it via browser control. So the director:

1. Recognizes the message came from the manager (the return loop), not the human.
2. Reads the live Claude Code session over the tandem MCP (send_to_session poll mode / relay read) to get the full context behind the message — never relies on just the typed summary.
3. Reviews against the spec.
4. Responds back DOWN into Claude Code with intent to continue — sends the next instruction / approval / fix to the manager via the tandem MCP (send_to_session), continuing the loop. The reply is a real next step, not "ok thanks."

So the round trip is: manager types into the chat tab -> director reads the session over MCP -> director sends the next move back down via MCP -> manager continues. No human tap, no human paste. The human can jump in at any turn and take over, then step back out.

> Honest limit: the manager "wakes" the chat by physically typing into the tab via the browser extension — it is not a server push. That's why Chrome + the extension + the machine being on are all required. Without them, fall back to the manual phone-tap-and-paste flow.

---

SESSION LAUNCH RULES (NON-NEGOTIABLE)

Every CC session spawned by tandem MUST:

1. Bypass permissions by default. The bridge handles this. The cwd allowlist is the real guardrail, enforced before spawn. Never widen the allowlist to work around a block.
2. Use the best available model. Default to the strongest current model (set via the model param on open_session, or claude --model opus for direct launches). Throwaway/probe sessions can use a smaller model. Real work = best model. No exceptions.
3. Effort: the worker runs on ultracode. The worker (builder) MUST be set to ultracode effort (/effort ultracode — xhigh thinking + dynamic workflow orchestration) on every real build session, no exceptions. The manager/director default to high. Only drop to medium/low for trivial probe sessions.
4. Fresh sessions per phase. Never reuse a bloated session. Context compacts, transcripts get huge, reads fail. Start clean for each phase.

---

WHICH SKILLS EACH LAYER READS

| Layer | Must read | Why | |---|---|---| | Director (chatbot) | This skill + tandem-engineering-workflow | Follows the brainstorm/spec/review/audit cycle with the human | | Manager CC | This skill + tandem-engineering-workflow | Same review discipline: plan mode, verify, never rubber-stamp | | Worker CC | This skill + tandem-agentic-engineering | Spawns agent teams, follows the agentic build cycle | | Sub-agents | Inherit from the worker's context | They get the spec from .claude/specs/[feature].md and the project CLAUDE.md |

How skills load: the chatbot already has them (installed on the chat side). For Claude Code sessions, install these skills there too, or reference them from the project's CLAUDE.md / .claude/specs/.

---

THE WORKFLOW (TOP TO BOTTOM)

PHASE 0: HUMAN + DIRECTOR — BRAINSTORM & SPEC

(follows tandem-engineering-workflow Phase 0-2)

1. Human gives the goal in detail (or minimum, and the director asks the right questions).
2. Director researches: search GitHub, prior art, existing patterns. Pull from your own memory/RAG if you use one (see Memory below).
3. Honest debate. If the idea is bad, say so. Better way = present it.
4. Agree on the approach.
5. Director writes the full spec: phases, files, architecture, agent roster, test plan, Definition of Done.

PHASE 1: DIRECTOR -> MANAGER — HAND OFF THE SPEC

1. Director opens a Manager CC session in the project directory via the tandem MCP.
2. Director sends the spec + the manager's standing brief: the spec, the review bar, the escalation rules, the stored chat URL, and the instruction to read this skill.
3. Manager acknowledges, reads the spec, plans the work breakdown.
4. Manager seeds disk memory in ~/.tandem/manager// (MISSION.md, STATE.json, LOG.md) — including the return chat URL.

PHASE 2: MANAGER -> WORKER — DIRECT THE BUILD

1. Manager opens/relays to a Worker CC session.
2. Manager sends the worker one phase at a time, with the agent roster, the launch command, and the spec path.

PHASE 3: WORKER — AGENT TEAM EXECUTION

(follows tandem-agentic-engineering Phase 3)

1. Worker assembles the team (implementers + concurrent reviewer + standby research + test-automator) and runs the internal perfection loop.
2. Worker reports back to the manager when done or blocked.

PHASE 4: MANAGER — REVIEW & DECIDE

(follows tandem-engineering-workflow Phase 4)

1. Manager reads the actual diff (git diff), runs the tests itself, checks for spec drift, confirms the reviewer agent's report is present.
2. APPROVE -> log it, send next phase. REJECT -> log why, send specific fixes. BLOCKED -> escalate.

PHASE 5: REPORT UP (THE BROWSER LOOP)

1. When a milestone/question/completion is ready, the manager reports up via the browser return loop (above): types into the stored chat URL.
2. The director reads the session over MCP, reviews, and sends the next move back down. Loop continues until the goal is done.
3. Only buzz the human (phone push) on full goal completion or a real human-only question.

---

THE GOAL PROTOCOL (the heavy directive)

A GOAL is not a task. A task is "add a button." A GOAL is "build the feature" — something no single CC launch can finish, that must be hammered across many rounds until it is not just done but excellent. When the human triggers a GOAL, the system does NOT stop at first completion. It loops, critiques, redoes, and perfects until every layer agrees it's impeccable. Only then is the human notified.

Core principle

One launch is never enough. Real work needs many rounds. The system keeps going on its own, enforcing quality, until the standard is met — not until the first draft exists.

GOAL lifecycle

1. Human triggers the GOAL: "GOAL: [big objective]. Work until it's impeccable. Notify me when it's truly done or if you hit a question only I can answer."
2. Director writes the GOAL spec — the definition of "excellent," not just "done": objective + why, an explicit Definition of Done checklist, the review ladder (Correct -> Secure -> Readable -> Elegant -> Improves-the-whole), the minimum loop count (worker internal loops >= 3, managerworker rounds >= 5, ceiling 20+ or until perfect), and which questions are worth interrupting the human for.
3. Manager owns the GOAL — re-reads MISSION.md every round (survives compaction), tracks STATE.json, never declares done early.
4. Worker internal perfection loop (before EVER reporting up):

• a. Build: spawn the agent team. Implementers build, code-reviewer runs concurrent, test-automator writes tests in parallel.
• b. Self-review + enforce: the worker reviews the team's output; sloppy or incomplete work gets sent back to redo.
• c. Devil's advocate pass: spawn adversarial agents whose only

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Maxmedawar
• Source: Maxmedawar/tandem
• License: MIT
• Homepage: https://eFreedom.com

Install and usage instructions live in the source repository linked above.