---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "foundations-cmux-orchestration-field-guide"
title: "CMUX Orchestration Field Guide"
---

# CMUX Orchestration Field Guide

> 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

```text
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

- [CMUX](https://cmux.com/)
- [cmux extensions](https://github.com/johnlindquist/cmux-extensions)
- [Zellij](https://zellij.dev/)

## Related principles

- [Coordinate agents with a manager and worker panes](/topics/foundations-manager-worker-orchestration/)
- [Keep agent memory visible and grounded](/topics/foundations-visible-agent-memory/)

## Original references

- [Agent foundations: Coordinate agents with a manager and worker panes (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-02.html)
- [Agent foundations: Keep agent memory visible and grounded (authorized access required)](https://codex-workshop-followup.pages.dev/lesson-03.html)
