{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "foundations-cmux-orchestration-field-guide",
  "slug": "cmux-orchestration-field-guide",
  "title": "CMUX Orchestration Field Guide",
  "summary": "Use panes, browser tabs, and a manager agent without letting workers step on each other.",
  "category": "Execution",
  "tags": [
    "field guide",
    "cmux orchestration"
  ],
  "sources": [
    {
      "label": "Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-02.html"
    },
    {
      "label": "Agent foundations: Keep agent memory visible and grounded (authorized access required)",
      "url": "https://codex-workshop-followup.pages.dev/lesson-03.html"
    }
  ],
  "sourceUnits": [
    "field-guides/guides.mjs#cmux-orchestration/overview",
    "field-guides/guides.mjs#cmux-orchestration/decision",
    "field-guides/guides.mjs#cmux-orchestration/agentPrompt",
    "field-guides/guides.mjs#cmux-orchestration/stories",
    "field-guides/guides.mjs#cmux-orchestration/tips",
    "field-guides/guides.mjs#cmux-orchestration/refs"
  ],
  "collection": "foundations",
  "categoryId": "execution",
  "wordCount": 383,
  "url": "/topics/foundations-cmux-orchestration-field-guide/",
  "markdownUrl": "/markdown/foundations-cmux-orchestration-field-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/foundations-cmux-orchestration-field-guide.json",
  "headings": [
    {
      "id": "choose-the-right-mechanism",
      "text": "Choose the right mechanism",
      "level": 2
    },
    {
      "id": "agent-ready-prompt",
      "text": "Agent-ready prompt",
      "level": 2
    },
    {
      "id": "applied-stories",
      "text": "Applied stories",
      "level": 2
    },
    {
      "id": "route-migration-split",
      "text": "Route migration split",
      "level": 3
    },
    {
      "id": "bug-bash-control-room",
      "text": "Bug bash control room",
      "level": 3
    },
    {
      "id": "tips-and-gotchas",
      "text": "Tips and gotchas",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    },
    {
      "id": "related-principles",
      "text": "Related principles",
      "level": 2
    }
  ],
  "markdown": "# CMUX Orchestration Field Guide\n\n> Original source pages and recordings require authorized access. The full article text here is public.\n\nUse panes, browser tabs, and a manager agent without letting workers step on each other.\n\nUse this when one Codex session should coordinate multiple focused workers, a dev server, and browser verification.\n\n## Choose the right mechanism\n\n| Mechanism | Use when | Agent responsibility | Artifact |\n|---|---|---|---|\n| Manager pane | Human-facing planning and delegation | One agent owns status and decisions | .notes/cmux-manager.md |\n| Worker pane | Narrow research or implementation slice | One task, one output file | .notes/workers/<name>.md |\n| Browser pane | Local rendered proof | Keep visible app state nearby | .notes/browser-proof/<task>.md |\n| Server pane | Long-running dev server | Keep logs stable and inspectable | .notes/server-log.md |\n\n## Agent-ready prompt\n\n```text\nAct as the CMUX manager.\nInspect the current repo and create a pane plan before opening workers.\nEach worker gets one bounded task, writes one markdown receipt, and does not edit outside its assigned files.\nKeep a dev-server pane and browser-proof pane visible for web work.\nCollate findings into .notes/cmux-summary.md before asking me for decisions.\n```\n\n## Applied stories\n\n### Route migration split\n\n**Role:** Full-stack lead\n\nA Next.js migration needs source audit, implementation, browser proof, and docs update in parallel.\n\n**Agent brief:** Manager opens workers for route audit, component patch, browser proof, and docs. Only manager summarizes and asks for decisions.\n\n**Done when:**\n\n- worker receipts\n- server log\n- browser proof\n- single manager summary\n\n### Bug bash control room\n\n**Role:** Frontend lead\n\nSeveral agents should explore different app personas without losing track.\n\n**Agent brief:** Assign each pane a persona and require numbered findings, screenshots, severity, and reproducibility.\n\n**Done when:**\n\n- per-persona QA files\n- deduped summary\n- known false positives removed\n\n## Tips and gotchas\n\n- Give every pane a name and a single owner.\n- Use workers for gathering and narrow edits; keep decisions in the manager pane.\n- Put servers behind panes that need them so logs do not disappear.\n- Have Codex read worker screens/files back before summarizing.\n\n## References\n\n- [CMUX](https://cmux.com/)\n- [cmux extensions](https://github.com/johnlindquist/cmux-extensions)\n- [Zellij](https://zellij.dev/)\n\n## Related principles\n\n- [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/)\n- [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)"
}
