CMUX Orchestration Field Guide

Use panes, browser tabs, and a manager agent without letting workers step on each other.

Original source pages and recordings require authorized access. The full article text here is public.

Use panes, browser tabs, and a manager agent without letting workers step on each other.

Use this when one Codex session should coordinate multiple focused workers, a dev server, and browser verification.

Choose the right mechanism

Mechanism Use when Agent responsibility Artifact
Manager pane Human-facing planning and delegation One agent owns status and decisions .notes/cmux-manager.md
Worker pane Narrow research or implementation slice One task, one output file .notes/workers/<name>.md
Browser pane Local rendered proof Keep visible app state nearby .notes/browser-proof/<task>.md
Server pane Long-running dev server Keep logs stable and inspectable .notes/server-log.md

Agent-ready prompt

Act as the CMUX manager.
Inspect the current repo and create a pane plan before opening workers.
Each worker gets one bounded task, writes one markdown receipt, and does not edit outside its assigned files.
Keep a dev-server pane and browser-proof pane visible for web work.
Collate findings into .notes/cmux-summary.md before asking me for decisions.

Applied stories

Route migration split

Role: Full-stack lead

A Next.js migration needs source audit, implementation, browser proof, and docs update in parallel.

Agent brief: Manager opens workers for route audit, component patch, browser proof, and docs. Only manager summarizes and asks for decisions.

Done when:

  • worker receipts
  • server log
  • browser proof
  • single manager summary

Bug bash control room

Role: Frontend lead

Several agents should explore different app personas without losing track.

Agent brief: Assign each pane a persona and require numbered findings, screenshots, severity, and reproducibility.

Done when:

  • per-persona QA files
  • deduped summary
  • known false positives removed

Tips and gotchas

  • Give every pane a name and a single owner.
  • Use workers for gathering and narrow edits; keep decisions in the manager pane.
  • Put servers behind panes that need them so logs do not disappear.
  • Have Codex read worker screens/files back before summarizing.

References

Source references