Agent Setup 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.
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:
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:
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:
~/.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:
- open a helper pane next to the current work
- fork or compact the Codex conversation in the pane you are looking at
- export a Codex transcript into
.exports - focus or open a project workspace by directory
- run a visible multi-agent layout
- move from one-off helper commands to gated multi-step orchestration
- debug a shortcut that targets the wrong conversation
- prove where a command ran and what session it belonged 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:
The newest terminal, pane, or agent session is probably the one you meant.
What the workflow gives you now:
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
workspace -> pane -> surface/tab -> process/session -> receipt
| Layer | What It Means | What To Check |
|---|---|---|
workspace |
project container, usually with a current directory | cmux rpc workspace.current |
pane |
visible split region inside a workspace | pane_ref, cmux rpc pane.create |
surface |
addressable terminal/browser/editor target inside a pane | surface_ref, CMUX_SURFACE_ID |
tab |
human-facing label for a surface | tab_ref, CMUX_TAB_ID |
| process | running program | zsh, codex, tmux, xport, p-f, p-c |
| session | durable agent identity | Codex session UUID |
| receipt | proof you can inspect later | .exports/<timestamp>.md, registry, logs, reports |
Practical language:
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.
| Tool | Role | Use It For |
|---|---|---|
cmux |
GUI/socket/workspace orchestrator | workspaces, panes, surfaces, browser/editor panels, focused context, keyboard launchers |
tmux |
terminal multiplexer layout primitive | terminal-only layouts, persistent sessions, panes/windows, CLI fanout, muxai layouts |
Practical line:
cmux is the building. tmux is one kind of room layout inside the building.
Address The Current Context
Start here:
cmux identify
Look for:
caller: the surface that invoked the commandfocused: the surface cmux believes is focusedworkspace_ref: project/workspace targetpane_ref: visible split targetsurface_ref: addressable surface targettab_ref: human-facing tab targetsocket_path: socket used by local automation
For keyboard launchers, prefer the caller surface when present:
.caller.surface_ref // .focused.surface_ref
This prevents a shortcut from accidentally targeting a different visible pane.
Get The Current Workspace Correctly
Use:
cmux rpc workspace.current
Look for:
workspace.current_directoryworkspace_idwindow_id
Do not assume this works:
cmux top --workspace current --processes --flat --format tsv
Observed failure shape:
Error: Invalid workspace handle: current (expected UUID, ref like workspace:1, or index)
Rule:
"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:
CMUX_SURFACE_ID
CMUX_WORKSPACE_ID
CMUX_TAB_ID
CMUX_SOCKET_PATH
Quick check:
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:
cmux-run-surface "command"
Right split:
cmux-run-surface "pwd; echo surface=$CMUX_SURFACE_ID"
Below split:
cmux-run-surface --below "pwd; echo surface=$CMUX_SURFACE_ID"
What the launcher does:
cmux rpc workspace.current
-> cmux rpc pane.create
-> cmux rpc pane.surfaces
-> cmux send "<command>"
-> cmux send-key enter
How to know it worked:
- a new cmux pane appears
- the command text is visible in that pane
- Enter was submitted
- the command runs from the focused workspace cwd
CMUX_SURFACE_IDis set inside the new terminal
Focus Or Open A Project Workspace
Shortcut:
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:
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:
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:
Esc+P
Actual route:
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:
cmux-fork-focused-codex --dry-run --preflight-fork
Compact fork below:
cmux-fork-focused-codex --dry-run --below --preflight-compact
Shortcut mapping:
| Shortcut | Route |
|---|---|
Esc+P |
focused Codex session -> p-f |
Esc+Shift+P |
focused Codex session -> compact -> p-c below |
Esc+E |
export focused workspace transcript with cmux-xport |
Esc+M |
export transcript and open markdown |
Why this matters:
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:
cmux rpc pane.surfaces '{"pane_id":"pane:<id>","workspace_id":"workspace:<id>","window_id":"window:<id>"}'
Then resolve the Codex session through:
python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" \
--resolve-surface "surface:<stable-surface-id>"
Screen fallback exists, but should be fallback only:
python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" \
--resolve-surface "surface:<id>" --allow-screen
Export A Transcript
Shortcut:
Esc+E
Command:
cmux-xport
Route:
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:
ls -lt .exports | head
test -s "$(ls -t .exports/*.md | head -1)" && echo export:OK
Practical line:
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:
| Helper | What It Does Here |
|---|---|
xfl |
find the Codex session or thread you intend to work with |
xfc |
continue or fork from the chosen Codex context |
xport |
export a Codex conversation from the current project cwd |
p-f |
launch a forked Codex path after the target session is known |
p-c |
launch 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 -ic 'whence -w muxai; funcwhere muxai'
Use muxai when you want a terminal-only multi-agent room inside a surface.
Validate agent_chain:
zsh -ic 'whence -w agent_chain; funcwhere agent_chain'
Use it for software work where you want phase separation:
agent_chain "Explore the billing webhook duplicate-processing bug, plan the smallest safe patch, then implement only if tests can verify it."
Good uses:
- refactor with a real review gate
- bug investigation before edit
- small feature with a plan checkpoint
- risky implementation that needs a danger confirmation
Bad use:
agent_chain "fix everything"
Ask The Agent This
Route a helper pane:
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:
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:
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
| Goal | Confirmation |
|---|---|
| Identify current context | cmux identify shows caller/focused workspace, pane, surface, tab |
| Get current workspace | cmux rpc workspace.current shows cwd, workspace id, window id |
| Avoid fake current handle | no command depends on --workspace current |
| Create helper pane | cmux-run-surface "echo ok" opens a pane and runs from intended cwd |
| Route focused fork | dry-run prints CODEX_FORK_SESSION_ID=<uuid> p-f or p-c |
| Export transcript | .exports/<timestamp>.md exists and is non-empty |
| tmux layout present | tmux ls and tmux list-panes -a show expected panes |
| agent chain scoped | goal names a specific software bug or feature and verification command |
If It Goes Wrong
Invalid Workspace Handle
Bad:
cmux top --workspace current --processes --flat --format tsv
Correct:
cmux identify
cmux rpc workspace.current
cmux rpc workspace.list
Wrong Session Fork
Dry-run:
cmux-fork-focused-codex --dry-run --preflight-fork
Correct route:
focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID
Missing .exports
Check:
ls -lt .exports | head
Direct save shape:
CODEX_XPORT_SAVE_CWD=1 zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; xport'
Function Not Found
Check:
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
- Common cmux config:
~/.config/cmux/cmux.json - Common pane launcher:
~/.local/bin/cmux-run-surface - Common focused fork launcher:
~/.local/bin/cmux-fork-focused-codex - Common xport launcher:
~/.local/bin/cmux-xport - Common registry hook:
~/.codex/hooks/cmux-codex-session-registry.py - Common tmux helper source:
~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh - Common agent chain source:
~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh - tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html
- tmux GitHub wiki: https://github.com/tmux/tmux/wiki
- OpenAI Codex: https://openai.com/codex/
- Model Context Protocol: https://modelcontextprotocol.io/
- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html