Write the plan once. Let every machine work it.

The plan is illustrative. The message names, route strings and 📋 notice texts are the ones the hub and the worker exchange; the quota handoff follows the worker's live test.

How it works

From one call to merged work

The lead plans, the hub decides, workers execute, and nothing reaches “done” without a verdict.

1. 01

   The lead writes the plan

   Claude Code — or any MCP client — sends the feature as a single cortex_task_tree_create call: keys and dependsOn, the files each task will touch, the engine and model per task, a fallback chain, an optional pinned machine, and gates. The hub rejects cycles before anything runs.

   cortex_task_tree_create(tasks: [
     { key: "BILL", title: "Billing v2", kind: "group" },
     { key: "SCHEMA", parentKey: "BILL", title: "Invoices table + migration",
       files: ["db/schema/"], executor: "claude", model: "opus", priority: "high" },
     { key: "PDF", parentKey: "BILL", title: "Invoice PDF renderer",
       files: ["lib/pdf/"], executor: "agy", model: "claude-sonnet-5-5-low",
       fallback: [{ executor: "agy", model: "gemini-4-argon-low" }] },
     { key: "API", parentKey: "BILL", title: "Invoice endpoints",
       dependsOn: ["SCHEMA"], files: ["api/billing/"], executor: "codex" },
     // HOOK, UI, DOCS, E2E …
     { key: "SHIP", parentKey: "BILL", title: "Ship billing v2",
       kind: "gate", approver: "user", dependsOn: ["E2E", "DOCS", "PDF"] }
   ])

2. 02

   The dispatcher decides — deterministically

   Assignment is a pure function, selectAssignments(tasks, workers, quota, now), so every decision can be reproduced in a test. A task is ready when its dependencies are done and no running task holds a path under the same prefix. Priority goes first; a task returns to the machine that last ran it; pins and declines are honoured; routes that are out of quota are skipped.

3. 03

   A worker runs it in its own worktree

   worktree→setup→engine→testCommand→commit→push→PR→review

   Each task gets ~/.cortex/worker/<agentId>/wt/<taskId>. The worker runs the optional setup command, then the engine, then the test command — keeping the last 200 lines — commits <key>: <title>, pushes, and opens a PR with gh, or hands back a compare URL when gh isn't there.

4. 04

   Review closes the loop

   A finished task is in review, not done. The lead hears about it on its next Cortex tool call and gives a verdict.

   approveDone. Dependents become ready.

   reject + feedbackBack to the same branch, feedback in context.reviews.

   2 strikesTwo rejections or two failures escalate to Needs you.
5. 05

   Gates hold the line

   A gate is a node in the graph with an approver. approver: "lead" closes with cortex_task_review. approver: "user" closes only from the dashboard — the MCP tool refuses it — so an agent cannot wave its own release through.

Quota

Running out of quota is a routing event, not an outage

Every task carries a chain of routes. A limit on one machine, engine and model sends the task down the chain — with its commits — and ends at the project default before it ever waits.

… tail of any Cortex tool result the lead receives
---
📋 Conductor:
  E2E "Billing e2e tests" is waiting for capacity: every route is out of quota until 2026-10-17T14:00:00Z.
  SCHEMA "Invoices table + migration" is ready for review — https://github.com/acme/billing/pull/41 (tests attached)

Correctness

Built for machines that sleep, drop and reconnect

Laptops close, Wi-Fi drops, a worker gets started twice. None of that should duplicate work, lose it, or leak a key.

Dashboard

See the critical path before it slips

The /conductor plan view draws the task graph by dependency depth, with a lane per machine and one for the queue.

• Route chips on every node — agy·gemini-4-argon-low — so you see which engine and model a task is on right now.
• Progress bar split into done, in review, running, ready, waiting and blocked.
• Needs you panel for escalations and user gates, with approve, reject and clear-escalation in place.
• Workers and a fallback tally showing which machines are online and how often routes fell through.
• Reroute a task — executor, model, fallback, files or dependencies — without recreating it.
• Phase view for plans grouped into milestones, with a lane per machine plus the queue.

Setup

One line per machine

Run it inside a clone of the project. The script fetches the worker from your own hub, so every machine runs the version its hub expects. Node 20 or newer; no global install.

curl -fsSL https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.sh | CORTEX_API_KEY=<worker-api-key> bash -s -- start --daemon --hub https://<your-mcp-host>

$env:CORTEX_API_KEY="<worker-api-key>"; iwr -useb https://raw.githubusercontent.com/lktiep/cortex-hub/master/scripts/run-agent.ps1 -OutFile $env:TEMP\run-agent.ps1; powershell -NoProfile -ExecutionPolicy Bypass -File $env:TEMP\run-agent.ps1 start --daemon --hub https://<your-mcp-host>

Replace <worker-api-key> and <your-mcp-host>. In the dashboard, Settings → Run a worker shows both lines with your hub's address already filled in. Give workers their own API key, separate from the lead's.

Status

Where it stands — honestly

✅ means a test on master covers it and passes. 🔄 means it works but rests on a check nobody has run yet. 📋 means planned.

Know before you lean on it

1. Quota output is verified for agy only. Claude, Codex and Gemini limits are matched against fixtures until a live hit confirms them.
2. Locks are only as good as files. A task that doesn't list what it touches isn't protected from conflicts.
3. agy takes about two minutes to start a task, because it starts every MCP server it has. Trim its server list to shorten that.
4. Use separate keys for the lead and workers. Notices are delivered once per key, to whichever session asks first.
5. User gates live in the dashboard, and it has no login. Anyone who can open it can approve one.
6. Windows workers await a manual run of the checklist; the end-to-end test is skipped there.