Workspace and session routing: practical reference

Practical cmux/tmux orchestration reference with an agent setup prompt, workspace/pane/surface/session routing model, focused Codex fork and compact workflows, transcript exports, zsh helper integration, multi-agent layouts and gated chains, verification…

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 command
  • focused: the surface cmux believes is focused
  • workspace_ref: project/workspace target
  • pane_ref: visible split target
  • surface_ref: addressable surface target
  • tab_ref: human-facing tab target
  • socket_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_directory
  • workspace_id
  • window_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_ID is 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

Source references