---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-workspace-routing-reference"
title: "Workspace and session routing: practical reference"
---

# Workspace and session routing: practical reference

## Agent Setup Prompt

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

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

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

```text
~/.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:

```text
The newest terminal, pane, or agent session is probably the one you meant.
```

What the workflow gives you now:

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

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

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

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

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

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

- `workspace.current_directory`
- `workspace_id`
- `window_id`

Do not assume this works:

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

Observed failure shape:

```text
Error: Invalid workspace handle: current (expected UUID, ref like workspace:1, or index)
```

Rule:

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

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

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

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

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

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

```text
Esc+P
```

Actual route:

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

| 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:

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

```text
Esc+E
```

Command:

```bash
cmux-xport
```

Route:

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

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

- 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:

```text
agent_chain "fix everything"
```

## Ask The Agent This

Route a helper pane:

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

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

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

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

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

- 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

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
