Command a CMUX manager/worker layout playbook

Web developers already juggle dev servers, test runners, browser verification, and agent chats; this pattern turns that chaos into one visible Manager pane coordinating narrow worker panes. It matters most when a local app needs code changes plus runtime proof, because the Manager can inspect panes, send targeted tasks, read worker output, and keep the human focused on decisions instead of pane babysitting.

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

Web developers already juggle dev servers, test runners, browser verification, and agent chats; this pattern turns that chaos into one visible Manager pane coordinating narrow worker panes. It matters most when a local app needs code changes plus runtime proof, because the Manager can inspect panes, send targeted tasks, read worker output, and keep the human focused on decisions instead of pane babysitting.

Core principles

Copy-paste workflow

When to use: When you want to drive several agent panes in parallel but only talk to one. This sets up a Manager pane plus worker panes in CMUX using natural language; the Manager opens, inspects, and delegates to the workers while you only converse with the Manager.

Copy-paste prompt

You are the Manager agent running in my focused CMUX pane. I will only talk to you; you coordinate worker panes. Use the REAL cmux CLI (do not invent flags). Keep the upfront planning human-led — confirm the plan with me before delegating.

1. Build the layout. Open a worker surface to the right and create additional worker panes as needed:
     cmux new-split right
     cmux new-pane
   Name the tabs so they stay findable:
     cmux rename-tab "<role-name>"

2. Always inspect live state before acting on a worker:
     cmux --json tree        # full pane/surface tree as JSON (focused pane, refs, cwd)
     cmux list-panes         # enumerate worker panes

3. Delegate a task into a worker surface, then read its output back as context:
     cmux send -- "<TASK TEXT FOR THAT WORKER>"
     cmux read-screen        # read that worker's terminal text back

4. Loop: you (Manager) talk to me, workers do the research/implementation. Report status back to me; do not let workers drift without checking cmux --json tree.

Guardrail: prefer PANES over tab groups — tab groups are easy to lose track of.

How it works

  • cmux new-split right and cmux new-pane build the manager/worker layout; cmux rename-tab "<name>" keeps roles findable.
  • cmux --json tree returns the live window/workspace/pane/surface tree as JSON (focused pane, refs like pane:89/surface:126, working directory) — inspect it before acting.
  • cmux list-panes enumerates worker panes.
  • cmux send -- "<text>" injects a task into a worker surface; cmux read-screen reads that worker's terminal text back as context for the Manager.
  • The Manager talks to the human; workers do research/implementation. Keep upfront planning human-led.
  • Prefer panes over tab groups — tab groups are easy to lose track of.
  • Reference: CMUX.

Reusable skill

Install as ~/.agents/skills/cmux-orchestrate/SKILL.md, then restart Codex.

---
name: cmux-orchestrate
description: Trigger when the user wants to drive multiple terminal/agent panes in CMUX from natural language — build manager/worker layouts, open/arrange panes, inspect or send work to other panes. Do NOT trigger outside a CMUX workspace.
---

# CMUX orchestration

Act as the Manager agent: build a pane layout, inspect live state, and delegate work to worker panes using the REAL cmux CLI. Do not invent flags. Inspect with `cmux --json tree` before acting.

## Command map (real cmux CLI)

```bash
cmux new-split <left|right|up|down>   # split from the focused surface in a direction
cmux new-pane                         # create a pane (terminal or browser content)
cmux --json tree                      # full window/workspace/pane/surface tree as JSON
cmux list-panes                       # enumerate panes in the workspace
cmux send -- "<text>"                 # send a task into a terminal surface
cmux read-screen                      # read a surface's terminal text back as context
cmux rename-tab "<name>"              # name a tab so it stays findable
cmux focus-pane <ref>                 # focus a pane (ref like pane:89 or surface:126)
```

Handles accept UUIDs, refs like `workspace:2` / `pane:89` / `surface:126`, and indexes.

## Manager-worker pattern
1. Build the layout: `cmux new-split right`, then `cmux new-pane` for each worker; name them with `cmux rename-tab "<role>"`.
2. Before acting on any worker, inspect live state: `cmux --json tree` (focused pane, refs, cwd) and `cmux list-panes`.
3. Delegate work: `cmux send -- "<task>"` into a worker, then `cmux read-screen` to pull its output back as context.
4. You (Manager) talk to the human; workers do research/implementation. Report status back.

## Guardrails
- Prefer PANES over tab groups — tab groups are easy to lose track of.
- Only use inside a CMUX workspace.

Scenarios

Triage a broken localhost checkout flow

Role: As a full-stack Next.js developer shipping a checkout fix

A Next.js storefront runs locally, the checkout route intermittently loses cart state after refresh, and the developer needs one agent to coordinate source inspection, dev-server logs, and browser proof without manually switching between terminals.

As a full-stack Next.js developer, I want one CMUX Manager pane to spin up focused workers for server logs, cart-state source review, and browser validation, so that I can fix the checkout bug with visible evidence instead of trusting a single agent transcript.

Agent brief

You are the Manager agent in my focused CMUX pane. Do not implement yet. First inspect live CMUX state with `cmux --json tree` and `cmux list-panes`. Build a visible pane layout using only real CMUX commands: create worker panes with `cmux new-split right` and `cmux new-pane`, then name the workspace tab with `cmux rename-tab "checkout-triage"`. Create three worker roles: `server-log-worker`, `source-worker`, and `browser-proof-worker`. Send each worker a narrow task using `cmux send -- "<task>"`: server-log-worker runs or watches the local dev server and captures errors; source-worker inspects cart and checkout route code only; browser-proof-worker verifies the localhost checkout flow in a browser or browser-agent workflow and reports exact observed behavior. After each worker responds, read its visible terminal output with `cmux read-screen`, summarize conflicts between source, logs, and browser behavior, then propose the smallest fix. Expected output: a Manager report containing pane refs from `cmux --json tree`, each worker assignment, each worker result, the chosen fix plan, and the browser/dev-server proof shape required before merging.

Implementation references

Open reference

Open reference

Open reference

cmux --json tree
cmux list-panes
cmux new-split right
cmux new-pane
cmux send -- "<task>"
cmux read-screen
cmux rename-tab "checkout-triage"

Browser verification

Use the browser-proof-worker for runtime proof: open the local checkout URL, take an accessibility-style snapshot of the page state, click through cart → checkout → refresh/back navigation, fill only safe test fields, and report URL, visible cart count, console/runtime errors, and whether state survives refresh. If a CMUX browser pane is available, keep that proof visible beside the Manager; otherwise use the project's existing browser automation or local browser and paste the observation back into the worker pane.

Definition of done

  • Manager report includes the live CMUX pane refs from cmux --json tree and the named roles assigned to each worker.
  • Dev-server or test-runner output is copied from a worker via cmux read-screen, not summarized from memory.
  • Browser proof includes the exact localhost route, user actions, visible before/after state, and any console/runtime error text.
  • A final review artifact lists the minimal code area to change and the verification commands or browser steps to rerun.

Failure modes and mitigations

  • The Manager delegates before inspecting live state; mitigate by requiring cmux --json tree and cmux list-panes before every send/read cycle.
  • Workers drift into broad refactors; mitigate by assigning each worker one narrow responsibility and having the Manager reject unrelated changes.
  • The browser worker reports success without proof; mitigate by requiring concrete URL, visible UI state, action sequence, and error/log evidence.

Coordinate a design-drift review before touching CSS

Role: As a frontend engineer maintaining a dashboard UI

A dashboard page has visual drift across cards, filters, and responsive layout after several agent-generated edits, and the developer wants separate workers to inspect current code, compare live UI behavior, and propose a bounded cleanup.

As a frontend engineer, I want a CMUX Manager to coordinate code, browser, and review workers before editing CSS, so that cleanup is based on current source and visible UI proof rather than vague design taste.

Agent brief

You are the Manager agent in my focused CMUX pane. Keep the human interaction surface to you only. Use `cmux --json tree` and `cmux list-panes` first. Create a visible Manager/worker layout with `cmux new-split right` and `cmux new-pane`; name the tab `dashboard-drift-review` with `cmux rename-tab "dashboard-drift-review"`. Create workers named `current-code-worker`, `responsive-browser-worker`, and `cleanup-plan-worker`. Use `cmux send -- "<task>"` to assign: current-code-worker identifies the current dashboard route, component files, and styling sources; responsive-browser-worker opens the local dashboard in a browser and records desktop and narrow-width observations; cleanup-plan-worker waits for the first two worker outputs, then drafts a small numbered cleanup plan with options A/B/C and a recommended pick. Read worker panes with `cmux read-screen`. Expected output: a numbered implementation plan that says which files are source of truth, what the browser showed, which visual issues are real, and which cleanup option the Manager recommends before implementation.

Implementation references

Open reference

Open reference

Open reference

Open reference

cmux --json tree
cmux list-panes
cmux send -- "<task>"
cmux read-screen
cmux rename-tab "dashboard-drift-review"

Browser verification

Use a CMUX browser pane or local browser verification to inspect the dashboard at desktop and narrow widths. The browser worker should capture a snapshot-style summary of headings, card order, filter controls, overflow, empty states, and any console errors; click filters and navigation only enough to prove whether drift is visual, state-related, or route-specific.

Definition of done

  • Manager names the CMUX tab and can list all worker panes with cmux list-panes.
  • Current-code-worker identifies the actual source files instead of relying on memory.
  • Responsive-browser-worker provides desktop and narrow-width observations with route and visible-state evidence.
  • Cleanup-plan-worker produces numbered options with a recommended pick, so the human can steer with a terse choice such as 2B.

Failure modes and mitigations

  • The agent treats design.md or memory as more authoritative than the current code; mitigate by making current-code-worker inspect the live repo first.
  • The browser check becomes a full QA swarm; mitigate by limiting it to the dashboard route, two viewport sizes, and the specific drift symptoms.
  • The Manager hides worker uncertainty; mitigate by requiring each worker output to include what it verified and what it did not verify.

Run a bounded AFK manager check-in on parallel workers

Role: As a senior developer supervising several local agent tasks

Three workers are already running in CMUX on separate subtasks: one is fixing a flaky unit test, one is checking a build failure, and one is investigating docs or dependency usage. The developer wants the Manager to periodically inspect panes and answer simple blocking questions, but not run forever.

As a senior developer, I want a CMUX Manager to check worker panes at a fixed interval with a hard stop condition, so that parallel work keeps moving while I step away without creating an unbounded autonomous loop.

Agent brief

You are the Manager agent in my focused CMUX pane. Start by creating a timestamp in your notes and inspect live CMUX state with `cmux --json tree` and `cmux list-panes`. Do not create new broad goals. Identify the existing worker panes by role, cwd, visible command, or recent terminal text. Every check-in cycle, use `cmux read-screen` to read each worker pane, summarize status, and if a worker is blocked by a simple question, choose the safest reasonable answer only when it stays inside that worker's assigned task. Use `cmux send -- "<answer or nudge>"` only after confirming the target pane from `cmux --json tree`. Stop after the explicit bound I give you, or after 3 check-in cycles if no bound is provided. Expected output: a check-in ledger with timestamp, pane refs, worker status, any answers sent, any panes needing human attention, and final stop reason.

Implementation references

Open reference

Open reference

Open reference

Open reference

cmux --json tree
cmux list-panes
cmux read-screen
cmux send -- "<answer or nudge>"
cmux notify

Browser verification

Browser proof is only appropriate if one of the existing workers is assigned to a web-app runtime task. In that case, the Manager should ask that worker for the local URL, exact browser action taken, and visible result; otherwise the correct proof is terminal evidence from cmux read-screen, test logs, and the check-in ledger.

Definition of done

  • The Manager records a start timestamp and a hard stop condition before the loop begins.
  • Each cycle includes pane refs, worker status, and terminal evidence read from the worker pane.
  • Any cmux send -- "<answer or nudge>" action is tied to a verified target pane from cmux --json tree.
  • The final ledger states whether each worker is done, blocked, still running, or needs human review, plus the stop reason.

Failure modes and mitigations

  • The loop runs without a bound; mitigate by requiring a duration, target time, iteration cap, or default 3-cycle limit before starting.
  • The Manager answers high-risk questions for a worker; mitigate by only answering simple in-scope blockers and escalating destructive, production, credential, or broad architecture decisions to the human.
  • The Manager sends a message to the wrong pane; mitigate by rechecking cmux --json tree immediately before each cmux send.

Implementation notes

  • The Manager should inspect with cmux --json tree before acting and again before sending to a target pane; stale pane refs are how agents nudge the wrong worker.
  • Keep worker tasks narrow: one worker for logs, one for source, one for browser/runtime proof is usually better than three agents all editing the same files.
  • Prefer panes over tab groups for visible parallel work, because hidden tab groups are easy to lose track of during agent-heavy sessions.
  • Use cmux read-screen as evidence. Do not let the Manager summarize worker progress from memory or from optimistic worker claims.
  • Browser verification should prove live web behavior when the task is a web-app task; for non-browser tasks, terminal logs, test output, and a Manager ledger are stronger proof.
  • AFK-style loops need an explicit interval and stop condition. Without a bound, the workflow becomes token-burning theater.

Boundaries and caveats

  • Do not present CMUX browser automation skills as a taught this workflow workflow; use browser proof only where a web app needs runtime verification.
  • Do not prescribe Claude Code scheduling, Codex Mobile, tmux migration, Zellij, or Vault search as implementation requirements for this playbook.
  • Do not invent CMUX flags beyond the verified command map.
  • Do not turn workers loose on unrelated broad refactors; the taught pattern is Manager-led orchestration with narrow worker assignments.
  • Do not run unbounded AFK loops or let a Manager approve risky production, credential, billing, deployment, or destructive actions without the human.

Agent reference map

Existing CMUX manager/worker prompt

Use this as the copy-paste baseline for Manager behavior, worker delegation, live-state inspection, and the human-led planning guardrail.

Open reference

CMUX orchestration skill

Use this as the reusable Codex skill contract for triggering CMUX orchestration only inside a CMUX workspace and for staying on the real command surface.

Open reference

Verified CMUX CLI command map

Use this to avoid invented flags and to keep pane creation, state inspection, send/read, focus, and tab naming grounded in the verified commands.

Open reference

Lesson 02 validated references

Use this as the taught-concept source for agent-first tooling, natural-language terminal orchestration, cross-pane reading, manager-worker topology, and bounded AFK loops.

Open reference

Lesson 02 validation notes

Use this to stay inside the transcript-validated boundary and avoid reintroducing removed or merely mentioned tools as taught workflows.

Open reference

Command reference

These command shapes are version-specific. Use the installed tool’s help and the linked public repository when platform behavior differs.

These are REAL commands. Do not invent flags.

Panes / layout

  • cmux new-split <left|right|up|down> [flags] — split from the focused surface in a direction.
  • cmux new-pane [flags] — create a pane with terminal or browser content.
  • cmux new-workspace [--name <title>] [--description <text>] [--cwd <path>] [--command <text>] [--layout <json>] [--focus <true|false>]
  • cmux focus-pane [--pane <id|ref> | <ref>]
  • cmux list-panes — enumerate panes in a workspace.
  • cmux tree [flags] / cmux --json tree — print the window/workspace/pane/surface tree (JSON with --json).

Live cmux --json tree returns an object with active (focused pane/surface refs, is_browser_surface, etc.) plus the full tree — this is the "CMUX state as JSON" / "inspect" the workflow uses (focused pane, refs, working directory).

Reading / sending

  • cmux read-screen [flags] — read terminal text from a surface back as context.
  • cmux send [flags] -- <text> — send text to a terminal surface.
  • cmux send-key <key> — send one key.

Tabs / markdown / notifications

  • cmux rename-tab "<name>" (compat wrapper for cmux tab-action rename).
  • cmux markdown open <path> [--direction <left|right|up|down>] [--focus <true|false>] — open a markdown file in a formatted viewer panel with live file watching (auto-refresh). This is the "live Markdown side pane" tracker.
  • cmux notify — send a notification to a workspace/surface.
  • cmux events — stream reconnectable cmux events as newline-delimited JSON (agent-readable telemetry / audit log).

Global options (before the command)

--socket <path>, --password <value>, --json, --id-format <refs|uuids|both>, --window <id|ref|index>.

Handles accept UUIDs, refs like workspace:2 / pane:89 / surface:126, and indexes.

Source references