Section 04

Agentic Dev Environment / Orchestrator

Set up the local cmux/tmux agent orchestration files and configuration for this software project. Inspect the existing local files first, preserve any working behavior, and crea...


setup agent prompt
Set up the local cmux/tmux agent orchestration files and configuration for this software project. Inspect the existing local files first, preserve any working behavior, and create or update only the narrow launcher, hook, and zsh helper pieces needed for reliable routing.

Work step by step:

1. Confirm prerequisites and current routing context.
   - Run `which cmux`, `which tmux`, `which zsh`, `which python3`, and `which node`.
   - Run `cmux identify` and capture `caller`, `focused`, `workspace_ref`, `pane_ref`, `surface_ref`, `tab_ref`, and `socket_path`.
   - Run `cmux rpc workspace.current` and capture `workspace.current_directory`, `workspace_id`, and `window_id`.
   - If the current workspace cwd is not the intended project, use `cmux-focus-or-open-workspace /path/to/project`, then re-run the checks.
   - Never use `--workspace current` as a workspace handle. Resolve the current workspace first, then use the explicit id or ref.

2. Inspect or create the cmux launcher files.
   - `~/.config/cmux/cmux.json`
   - `~/.config/cmux/scripts/cmux-xport.sh`
   - `~/.local/bin/cmux-run-surface`
   - `~/.local/bin/cmux-fork-focused-codex`
   - `~/.local/bin/cmux-focus-or-open-workspace`
   - `~/.local/bin/cmux-xport`
   - `~/.local/bin/cmux-xport-markdown`
   Ensure executable launcher files are executable. Do not overwrite existing scripts blindly; diff or summarize the existing behavior first.

3. Wire workspace, pane, surface, tab, process, and session mapping.
   - Treat the routing graph as `workspace -> pane -> surface/tab -> process/session -> receipt`.
   - `cmux-run-surface` must resolve the workspace with `cmux rpc workspace.current`, create a pane with explicit workspace/window/pane refs, inspect surfaces with `cmux rpc pane.surfaces`, send the requested command to the intended surface, and press Enter.
   - Support right split by default and `--below` for below split.
   - Confirm commands run from the focused workspace cwd and inherit `CMUX_SURFACE_ID`, `CMUX_WORKSPACE_ID`, `CMUX_TAB_ID`, and `CMUX_SOCKET_PATH`.

4. Set up focused Codex session routing.
   - `cmux-fork-focused-codex` must prefer `.caller.surface_ref` when present, then fall back to `.focused.surface_ref`.
   - Normalize short surface refs through `cmux rpc pane.surfaces '{"pane_id":"pane:<id>","workspace_id":"workspace:<id>","window_id":"window:<id>"}'`.
   - Resolve the Codex session through `python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" --resolve-surface "surface:<stable-surface-id>"`.
   - Hand off fork mode as `CODEX_FORK_SESSION_ID=<uuid> p-f`.
   - Hand off compact mode as `CODEX_FORK_SESSION_ID=<uuid> p-c`, with `--below` supported.
   - Do not use `fork --last` as a substitute for focused surface routing.

5. Inspect or create the Codex hook registry files.
   - `~/.codex/hooks/cmux-codex-session-registry.py`
   - `~/.codex/hooks/cmux-auto-name-tab.zsh`
   - `~/.codex/hooks/codex-thread-name-set.mjs`
   The registry must map stable cmux surface ids to Codex session UUIDs. Keep screen scraping or `--allow-screen` as fallback only, and report when fallback was required.

6. Set up transcript exports.
   - `cmux-xport` must resolve the focused workspace cwd, `cd` there, set `CODEX_XPORT_SAVE_CWD=1`, load the zsh helper path that defines `xport`, copy the transcript to the clipboard when available, and save a non-empty markdown file under `.exports/<timestamp>.md`.
   - `cmux-xport-markdown` should open or surface the saved markdown export without pasting the full transcript into chat.

7. Wire tmux, muxai, and agent_chain.
   - Inspect `~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh`, `~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh`, and `~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh`.
   - Confirm `muxai` resolves for terminal-only multi-agent layouts.
   - Confirm `agent_chain` resolves for gated multi-step software work.
   - If a helper is a zsh function (`p-f`, `p-c`, `xport`, `xfl`, `xfc`, `muxai`, `agent_chain`), either load it through the intended zsh startup path or provide a small executable wrapper for non-zsh callers.

8. Respect privacy boundaries.
   - Do not paste full `env` output.
   - Do not expose API keys, tokens, cookies, provider variables, private endpoints, or credentials from config, hook, shell, or transcript files.
   - Do not copy private local config verbatim when a structure summary is enough.
   - Keep transcript exports local under `.exports` unless explicitly asked to share them.
   - Report session ids and surface ids only when needed to prove routing, and avoid including transcript content in the report.

9. Run verification commands before declaring setup complete.
   - `cmux identify`
   - `cmux rpc workspace.current`
   - `printf 'surface=%s\nworkspace=%s\ntab=%s\nsocket=%s\n' "$CMUX_SURFACE_ID" "$CMUX_WORKSPACE_ID" "$CMUX_TAB_ID" "$CMUX_SOCKET_PATH"`
   - `cmux-run-surface "pwd; echo surface=$CMUX_SURFACE_ID"`
   - `cmux-run-surface --below "pwd; echo surface=$CMUX_SURFACE_ID"`
   - `cmux-fork-focused-codex --dry-run --preflight-fork`
   - `cmux-fork-focused-codex --dry-run --below --preflight-compact`
   - `ls -lt .exports | head`
   - `test -s "$(ls -t .exports/*.md | head -1)" && echo export:OK`
   - `zsh -ic 'whence -w muxai; funcwhere muxai'`
   - `zsh -ic 'whence -w agent_chain; funcwhere agent_chain'`
   - `zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport xfl xfc'`

10. Report results plainly.
   - List files inspected.
   - List files created or edited.
   - List files intentionally left untouched.
   - For each verification command, report pass/fail and the key output.
   - If anything is missing, broken, private, or ambiguous, stop and explain the blocker instead of claiming setup is complete.

Workflow route

Agentic Dev Environment / Orchestrator

Set up the local cmux/tmux agent orchestration files and configuration for this software project. Inspect the existing local files first, preserve any working behavior, and crea...

Eggo routes the active session to the correct visible surface for the Agentic Dev Environment / Orchestrator workflow, making the page's operating move visible.
Intent

Name the software-workflow decision before launching work.

Evidence

Inspect the file, command, log, prompt, or recording that proves the state.

Route

Pick the narrow agent, tool, shell, or council path that matches the problem.

Verify

Confirm the result with output, screenshots, receipts, or saved decisions.

  1. Big Idea
  2. Try This Now
  3. Files To Inspect
  4. When To Reach For This
  5. How This Used To Work
  6. The Mental Model
the correct pane lights up and the proof card stays attached

Big Idea

Phase: Routing And Composition - once context and helper boundaries are clear, route the work to the right workspace, pane, and session.

Focused context is a routing problem, not a prompt problem.

Try This Now

From the project workspace, run: cmux identify. Then run: cmux rpc workspace.current. Do not launch a helper pane until the workspace cwd and focused surface match the project you mean.

Once you have the right project context, shell environment, and zsh helpers, the next question is:

snippet-1
Which agent is doing what, in which workspace, in which pane, against which
session, and what proof can I save?

Treat the environment as an addressable graph:

snippet-2
workspace -> pane -> surface/tab -> process/session -> receipt

A better prompt cannot fix bad routing. First route the action to the correct surface and session.

Files To Inspect

Common local orchestrator files and scripts:

snippet-3
~/.config/cmux/cmux.json
~/.config/cmux/scripts/cmux-xport.sh
~/.local/bin/cmux-run-surface
~/.local/bin/cmux-fork-focused-codex
~/.local/bin/cmux-focus-or-open-workspace
~/.local/bin/cmux-xport
~/.local/bin/cmux-xport-markdown
~/.codex/hooks/cmux-codex-session-registry.py
~/.codex/hooks/cmux-auto-name-tab.zsh
~/.codex/hooks/codex-thread-name-set.mjs
~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh
~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh
~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh

When To Reach For This

Use this workflow when you need to:

Focus on practical routing for software project work. Skip tmux and cmux internals that do not affect the current workspace, pane, session, or receipt.

How This Used To Work

What you used to expect:

snippet-4
The newest terminal, pane, or agent session is probably the one you meant.

What the workflow gives you now:

snippet-5
Ask the orchestrator where you are, use stable ids, launch helpers in known
panes, and save transcripts when the session becomes part of the work.

The Mental Model

snippet-6
workspace -> pane -> surface/tab -> process/session -> receipt
LayerWhat It MeansWhat To Check
workspaceproject container, usually with a current directorycmux rpc workspace.current
panevisible split region inside a workspacepane_ref, cmux rpc pane.create
surfaceaddressable terminal/browser/editor target inside a panesurface_ref, CMUX_SURFACE_ID
tabhuman-facing label for a surfacetab_ref, CMUX_TAB_ID
processrunning programzsh, codex, tmux, xport, p-f, p-c
sessiondurable agent identityCodex session UUID
receiptproof you can inspect later.exports/<timestamp>.md, registry, logs, reports

Practical language:

snippet-7
A pane is where work is visible.
A session is what work belongs to.
A receipt is what makes work resumable.

cmux vs tmux

cmux and tmux solve different layers.

ToolRoleUse It For
cmuxGUI/socket/workspace orchestratorworkspaces, panes, surfaces, browser/editor panels, focused context, keyboard launchers
tmuxterminal multiplexer layout primitiveterminal-only layouts, persistent sessions, panes/windows, CLI fanout, muxai layouts

Practical line:

snippet-8
cmux is the building. tmux is one kind of room layout inside the building.

Address The Current Context

Start here:

bash
cmux identify

Look for:

For keyboard launchers, prefer the caller surface when present:

snippet-10
.caller.surface_ref // .focused.surface_ref

This prevents a shortcut from accidentally targeting a different visible pane.

Get The Current Workspace Correctly

Use:

bash
cmux rpc workspace.current

Look for:

Do not assume this works:

bash
cmux top --workspace current --processes --flat --format tsv

Observed failure shape:

snippet-13
Error: Invalid workspace handle: current (expected UUID, ref like workspace:1, or index)

Rule:

snippet-14
"Current" is a question, not a workspace handle.
Ask cmux for current state, then use the returned explicit ref/id.

Know The cmux Environment Variables

Inside cmux terminal surfaces, scripts can use:

snippet-15
CMUX_SURFACE_ID
CMUX_WORKSPACE_ID
CMUX_TAB_ID
CMUX_SOCKET_PATH

Quick check:

bash
printf 'surface=%s\nworkspace=%s\ntab=%s\nsocket=%s\n' \
  "$CMUX_SURFACE_ID" "$CMUX_WORKSPACE_ID" "$CMUX_TAB_ID" "$CMUX_SOCKET_PATH"

If those values are empty, you may not be inside a cmux terminal surface, or the process may not have inherited the cmux environment.

Create A Helper Pane

Shortcut:

snippet-17
cmux-run-surface "command"

Right split:

bash
cmux-run-surface "pwd; echo surface=$CMUX_SURFACE_ID"

Below split:

bash
cmux-run-surface --below "pwd; echo surface=$CMUX_SURFACE_ID"

What the launcher does:

snippet-20
cmux rpc workspace.current
-> cmux rpc pane.create
-> cmux rpc pane.surfaces
-> cmux send "<command>"
-> cmux send-key enter

How to know it worked:

Focus Or Open A Project Workspace

Shortcut:

snippet-21
cmux-focus-or-open-workspace /path/to/project

Use this when the problem starts with a directory or repo, not with a visible pane.

What the launcher should do:

snippet-22
find existing cmux workspace for the project
-> focus it if it exists
-> open a new workspace if it does not
-> keep later helper panes and forks anchored to that project cwd

How to know it worked:

bash
cmux rpc workspace.current

Look for the expected project directory in workspace.current_directory before launching helper panes or agent chains.

Fork The Focused Codex Session

Shortcut:

snippet-24
Esc+P

Actual route:

snippet-25
Esc+P
-> cmux-fork-focused-codex --preflight-fork
-> cmux identify
-> caller/focused surface
-> cmux rpc pane.surfaces
-> stable surface id
-> cmux-codex-session-registry.py --resolve-surface
-> Codex session id
-> CODEX_FORK_SESSION_ID=<session-id> p-f
-> cmux-run-surface
-> new pane

Dry-run first:

bash
cmux-fork-focused-codex --dry-run --preflight-fork

Compact fork below:

bash
cmux-fork-focused-codex --dry-run --below --preflight-compact

Shortcut mapping:

ShortcutRoute
Esc+Pfocused Codex session -> p-f
Esc+Shift+Pfocused Codex session -> compact -> p-c below
Esc+Eexport focused workspace transcript with cmux-xport
Esc+Mexport transcript and open markdown

Why this matters:

snippet-28
fork --last is not the same as fork the conversation in the focused pane.

Stable Surface IDs And The Registry

Short refs such as surface:38 are useful in current output, but they are not the durable routing key.

Focused fork should normalize the short surface ref through:

bash
cmux rpc pane.surfaces '{"pane_id":"pane:<id>","workspace_id":"workspace:<id>","window_id":"window:<id>"}'

Then resolve the Codex session through:

bash
python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" \
  --resolve-surface "surface:<stable-surface-id>"

Screen fallback exists, but should be fallback only:

bash
python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" \
  --resolve-surface "surface:<id>" --allow-screen

Export A Transcript

Shortcut:

snippet-32
Esc+E

Command:

bash
cmux-xport

Route:

snippet-34
cmux-xport
-> cmux rpc workspace.current
-> cd focused workspace cwd
-> CODEX_XPORT_SAVE_CWD=1
-> source ~/.config/zsh/conf.d/40-ai.zsh
-> xport
-> clipboard
-> .exports/<timestamp>.md
-> notification

How to know it worked:

bash
ls -lt .exports | head
test -s "$(ls -t .exports/*.md | head -1)" && echo export:OK

Practical line:

snippet-36
Clipboard is convenience. .exports is the durable receipt.

How Helpers Connect To Routing

First identify whether the helper is a zsh function, alias, executable, or environment variable.

Then route it to the workspace, pane, surface, or session where it should run.

Common bridge helpers:

HelperWhat It Does Here
xflfind the Codex session or thread you intend to work with
xfccontinue or fork from the chosen Codex context
xportexport a Codex conversation from the current project cwd
p-flaunch a forked Codex path after the target session is known
p-claunch a compacted Codex path after the target session is known

If the command is a zsh function, either run it through the zsh startup path that loads it or use the executable wrapper that the orchestrator expects.

tmux Layouts And Agent Chains

Validate muxai:

zsh
zsh -ic 'whence -w muxai; funcwhere muxai'

Use muxai when you want a terminal-only multi-agent room inside a surface.

Validate agent_chain:

zsh
zsh -ic 'whence -w agent_chain; funcwhere agent_chain'

Use it for software work where you want phase separation:

zsh
agent_chain "Explore the billing webhook duplicate-processing bug, plan the smallest safe patch, then implement only if tests can verify it."

Good uses:

Bad use:

snippet-40
agent_chain "fix everything"

Ask The Agent This

Route a helper pane:

snippet-41
Use the cmux orchestrator source files.

Open a helper pane for this software project. It should run from the focused
workspace cwd and inspect the checkout flow failure without editing files.
Use cmux routing, not manual terminal instructions. Tell me how to confirm the
pane was created and where to check logs if it fails.

Debug a wrong focused fork:

snippet-42
Esc+P forked the wrong Codex conversation.

Inspect the focused-fork route: `cmux identify`, caller versus focused surface,
`cmux rpc pane.surfaces`, stable surface lookup, the Codex cmux registry,
`CODEX_FORK_SESSION_ID`, and the `p-f` handoff. Do not assume `fork --last` is
correct. Give me the dry-run command that proves the target session id before
launching.

Export a conversation:

snippet-43
Export the focused Codex conversation for this project.

Use `cmux-xport` or the equivalent `CODEX_XPORT_SAVE_CWD=1` zsh path. Confirm
the export was copied to the clipboard and saved under `.exports`. Do not paste
the whole transcript back into chat.

What To Confirm / How To Know It Worked

GoalConfirmation
Identify current contextcmux identify shows caller/focused workspace, pane, surface, tab
Get current workspacecmux rpc workspace.current shows cwd, workspace id, window id
Avoid fake current handleno command depends on --workspace current
Create helper panecmux-run-surface "echo ok" opens a pane and runs from intended cwd
Route focused forkdry-run prints CODEX_FORK_SESSION_ID=<uuid> p-f or p-c
Export transcript.exports/<timestamp>.md exists and is non-empty
tmux layout presenttmux ls and tmux list-panes -a show expected panes
agent chain scopedgoal names a specific software bug or feature and verification command

If It Goes Wrong

Invalid Workspace Handle

Bad:

bash
cmux top --workspace current --processes --flat --format tsv

Correct:

bash
cmux identify
cmux rpc workspace.current
cmux rpc workspace.list

Wrong Session Fork

Dry-run:

bash
cmux-fork-focused-codex --dry-run --preflight-fork

Correct route:

snippet-47
focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID

Missing .exports

Check:

bash
ls -lt .exports | head

Direct save shape:

zsh
CODEX_XPORT_SAVE_CWD=1 zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; xport'

Function Not Found

Check:

zsh
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport'

Some orchestration commands are zsh functions. Launch them through zsh or provide executable wrappers.

References And Resources