{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-workspace-routing-reference",
  "slug": "workspace-routing-reference",
  "title": "Workspace and session routing: practical reference",
  "summary": "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…",
  "category": "Execution",
  "tags": [
    "cmux",
    "tmux",
    "orchestration"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Agent Setup Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Big Idea",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Try This Now",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Files To Inspect",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/When To Reach For This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/How This Used To Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/The Mental Model",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/cmux vs tmux",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Address The Current Context",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Get The Current Workspace Correctly",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Know The cmux Environment Variables",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Create A Helper Pane",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Focus Or Open A Project Workspace",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Fork The Focused Codex Session",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Stable Surface IDs And The Registry",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Export A Transcript",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/How Helpers Connect To Routing",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/tmux Layouts And Agent Chains",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/Ask The Agent This",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/What To Confirm / How To Know It Worked",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Invalid Workspace Handle",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Wrong Session Fork",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Missing `.exports`",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/If It Goes Wrong/Function Not Found",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/cheatsheets/04-agentic-dev-environment-orchestrator.md#04. Agentic Dev Environment / Orchestrator/References And Resources",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "execution",
  "wordCount": 2703,
  "url": "/topics/codex-workspace-routing-reference/",
  "markdownUrl": "/markdown/codex-workspace-routing-reference.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-workspace-routing-reference.json",
  "headings": [
    {
      "id": "agent-setup-prompt",
      "text": "Agent Setup Prompt",
      "level": 2
    },
    {
      "id": "big-idea",
      "text": "Big Idea",
      "level": 2
    },
    {
      "id": "try-this-now",
      "text": "Try This Now",
      "level": 2
    },
    {
      "id": "files-to-inspect",
      "text": "Files To Inspect",
      "level": 2
    },
    {
      "id": "when-to-reach-for-this",
      "text": "When To Reach For This",
      "level": 2
    },
    {
      "id": "how-this-used-to-work",
      "text": "How This Used To Work",
      "level": 2
    },
    {
      "id": "the-mental-model",
      "text": "The Mental Model",
      "level": 2
    },
    {
      "id": "cmux-vs-tmux",
      "text": "cmux vs tmux",
      "level": 2
    },
    {
      "id": "address-the-current-context",
      "text": "Address The Current Context",
      "level": 2
    },
    {
      "id": "get-the-current-workspace-correctly",
      "text": "Get The Current Workspace Correctly",
      "level": 2
    },
    {
      "id": "know-the-cmux-environment-variables",
      "text": "Know The cmux Environment Variables",
      "level": 2
    },
    {
      "id": "create-a-helper-pane",
      "text": "Create A Helper Pane",
      "level": 2
    },
    {
      "id": "focus-or-open-a-project-workspace",
      "text": "Focus Or Open A Project Workspace",
      "level": 2
    },
    {
      "id": "fork-the-focused-codex-session",
      "text": "Fork The Focused Codex Session",
      "level": 2
    },
    {
      "id": "stable-surface-ids-and-the-registry",
      "text": "Stable Surface IDs And The Registry",
      "level": 2
    },
    {
      "id": "export-a-transcript",
      "text": "Export A Transcript",
      "level": 2
    },
    {
      "id": "how-helpers-connect-to-routing",
      "text": "How Helpers Connect To Routing",
      "level": 2
    },
    {
      "id": "tmux-layouts-and-agent-chains",
      "text": "tmux Layouts And Agent Chains",
      "level": 2
    },
    {
      "id": "ask-the-agent-this",
      "text": "Ask The Agent This",
      "level": 2
    },
    {
      "id": "what-to-confirm-how-to-know-it-worked",
      "text": "What To Confirm / How To Know It Worked",
      "level": 2
    },
    {
      "id": "if-it-goes-wrong",
      "text": "If It Goes Wrong",
      "level": 2
    },
    {
      "id": "invalid-workspace-handle",
      "text": "Invalid Workspace Handle",
      "level": 3
    },
    {
      "id": "wrong-session-fork",
      "text": "Wrong Session Fork",
      "level": 3
    },
    {
      "id": "missing-exports",
      "text": "Missing `.exports`",
      "level": 3
    },
    {
      "id": "function-not-found",
      "text": "Function Not Found",
      "level": 3
    },
    {
      "id": "references-and-resources",
      "text": "References And Resources",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Workspace and session routing: practical reference\n\n## Agent Setup Prompt\n\n```text\nSet 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.\n\nWork step by step:\n\n1. Confirm prerequisites and current routing context.\n   - Run `which cmux`, `which tmux`, `which zsh`, `which python3`, and `which node`.\n   - Run `cmux identify` and capture `caller`, `focused`, `workspace_ref`, `pane_ref`, `surface_ref`, `tab_ref`, and `socket_path`.\n   - Run `cmux rpc workspace.current` and capture `workspace.current_directory`, `workspace_id`, and `window_id`.\n   - If the current workspace cwd is not the intended project, use `cmux-focus-or-open-workspace /path/to/project`, then re-run the checks.\n   - Never use `--workspace current` as a workspace handle. Resolve the current workspace first, then use the explicit id or ref.\n\n2. Inspect or create the cmux launcher files.\n   - `~/.config/cmux/cmux.json`\n   - `~/.config/cmux/scripts/cmux-xport.sh`\n   - `~/.local/bin/cmux-run-surface`\n   - `~/.local/bin/cmux-fork-focused-codex`\n   - `~/.local/bin/cmux-focus-or-open-workspace`\n   - `~/.local/bin/cmux-xport`\n   - `~/.local/bin/cmux-xport-markdown`\n   Ensure executable launcher files are executable. Do not overwrite existing scripts blindly; diff or summarize the existing behavior first.\n\n3. Wire workspace, pane, surface, tab, process, and session mapping.\n   - Treat the routing graph as `workspace -> pane -> surface/tab -> process/session -> receipt`.\n   - `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.\n   - Support right split by default and `--below` for below split.\n   - Confirm commands run from the focused workspace cwd and inherit `CMUX_SURFACE_ID`, `CMUX_WORKSPACE_ID`, `CMUX_TAB_ID`, and `CMUX_SOCKET_PATH`.\n\n4. Set up focused Codex session routing.\n   - `cmux-fork-focused-codex` must prefer `.caller.surface_ref` when present, then fall back to `.focused.surface_ref`.\n   - Normalize short surface refs through `cmux rpc pane.surfaces '{\"pane_id\":\"pane:<id>\",\"workspace_id\":\"workspace:<id>\",\"window_id\":\"window:<id>\"}'`.\n   - Resolve the Codex session through `python3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" --resolve-surface \"surface:<stable-surface-id>\"`.\n   - Hand off fork mode as `CODEX_FORK_SESSION_ID=<uuid> p-f`.\n   - Hand off compact mode as `CODEX_FORK_SESSION_ID=<uuid> p-c`, with `--below` supported.\n   - Do not use `fork --last` as a substitute for focused surface routing.\n\n5. Inspect or create the Codex hook registry files.\n   - `~/.codex/hooks/cmux-codex-session-registry.py`\n   - `~/.codex/hooks/cmux-auto-name-tab.zsh`\n   - `~/.codex/hooks/codex-thread-name-set.mjs`\n   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.\n\n6. Set up transcript exports.\n   - `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`.\n   - `cmux-xport-markdown` should open or surface the saved markdown export without pasting the full transcript into chat.\n\n7. Wire tmux, muxai, and agent_chain.\n   - 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`.\n   - Confirm `muxai` resolves for terminal-only multi-agent layouts.\n   - Confirm `agent_chain` resolves for gated multi-step software work.\n   - 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.\n\n8. Respect privacy boundaries.\n   - Do not paste full `env` output.\n   - Do not expose API keys, tokens, cookies, provider variables, private endpoints, or credentials from config, hook, shell, or transcript files.\n   - Do not copy private local config verbatim when a structure summary is enough.\n   - Keep transcript exports local under `.exports` unless explicitly asked to share them.\n   - Report session ids and surface ids only when needed to prove routing, and avoid including transcript content in the report.\n\n9. Run verification commands before declaring setup complete.\n   - `cmux identify`\n   - `cmux rpc workspace.current`\n   - `printf 'surface=%s\\nworkspace=%s\\ntab=%s\\nsocket=%s\\n' \"$CMUX_SURFACE_ID\" \"$CMUX_WORKSPACE_ID\" \"$CMUX_TAB_ID\" \"$CMUX_SOCKET_PATH\"`\n   - `cmux-run-surface \"pwd; echo surface=$CMUX_SURFACE_ID\"`\n   - `cmux-run-surface --below \"pwd; echo surface=$CMUX_SURFACE_ID\"`\n   - `cmux-fork-focused-codex --dry-run --preflight-fork`\n   - `cmux-fork-focused-codex --dry-run --below --preflight-compact`\n   - `ls -lt .exports | head`\n   - `test -s \"$(ls -t .exports/*.md | head -1)\" && echo export:OK`\n   - `zsh -ic 'whence -w muxai; funcwhere muxai'`\n   - `zsh -ic 'whence -w agent_chain; funcwhere agent_chain'`\n   - `zsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport xfl xfc'`\n\n10. Report results plainly.\n   - List files inspected.\n   - List files created or edited.\n   - List files intentionally left untouched.\n   - For each verification command, report pass/fail and the key output.\n   - If anything is missing, broken, private, or ambiguous, stop and explain the blocker instead of claiming setup is complete.\n```\n\n## Big Idea\n\nPhase: Routing And Composition - once context and helper boundaries are clear, route the work to the right workspace, pane, and session.\n\nFocused context is a routing problem, not a prompt problem.\n\n## Try This Now\n\nFrom the project workspace, run: `cmux identify`.\nThen run: `cmux rpc workspace.current`.\nDo not launch a helper pane until the workspace cwd and focused surface match the project you mean.\n\nOnce you have the right project context, shell environment, and zsh helpers, the next question is:\n\n```text\nWhich agent is doing what, in which workspace, in which pane, against which\nsession, and what proof can I save?\n```\n\nTreat the environment as an addressable graph:\n\n```text\nworkspace -> pane -> surface/tab -> process/session -> receipt\n```\n\nA better prompt cannot fix bad routing. First route the action to the correct surface and session.\n\n## Files To Inspect\n\nCommon local orchestrator files and scripts:\n\n```text\n~/.config/cmux/cmux.json\n~/.config/cmux/scripts/cmux-xport.sh\n~/.local/bin/cmux-run-surface\n~/.local/bin/cmux-fork-focused-codex\n~/.local/bin/cmux-focus-or-open-workspace\n~/.local/bin/cmux-xport\n~/.local/bin/cmux-xport-markdown\n~/.codex/hooks/cmux-codex-session-registry.py\n~/.codex/hooks/cmux-auto-name-tab.zsh\n~/.codex/hooks/codex-thread-name-set.mjs\n~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh\n~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh\n~/.config/zsh/conf.d/49-ai-pipeline-wrappers.zsh\n```\n\n## When To Reach For This\n\nUse this workflow when you need to:\n\n- open a helper pane next to the current work\n- fork or compact the Codex conversation in the pane you are looking at\n- export a Codex transcript into `.exports`\n- focus or open a project workspace by directory\n- run a visible multi-agent layout\n- move from one-off helper commands to gated multi-step orchestration\n- debug a shortcut that targets the wrong conversation\n- prove where a command ran and what session it belonged to\n\nFocus on practical routing for software project work. Skip tmux and cmux internals that do not affect the current workspace, pane, session, or receipt.\n\n## How This Used To Work\n\nWhat you used to expect:\n\n```text\nThe newest terminal, pane, or agent session is probably the one you meant.\n```\n\nWhat the workflow gives you now:\n\n```text\nAsk the orchestrator where you are, use stable ids, launch helpers in known\npanes, and save transcripts when the session becomes part of the work.\n```\n\n## The Mental Model\n\n```text\nworkspace -> pane -> surface/tab -> process/session -> receipt\n```\n\n| Layer | What It Means | What To Check |\n| --- | --- | --- |\n| `workspace` | project container, usually with a current directory | `cmux rpc workspace.current` |\n| `pane` | visible split region inside a workspace | `pane_ref`, `cmux rpc pane.create` |\n| `surface` | addressable terminal/browser/editor target inside a pane | `surface_ref`, `CMUX_SURFACE_ID` |\n| `tab` | human-facing label for a surface | `tab_ref`, `CMUX_TAB_ID` |\n| process | running program | `zsh`, `codex`, `tmux`, `xport`, `p-f`, `p-c` |\n| session | durable agent identity | Codex session UUID |\n| receipt | proof you can inspect later | `.exports/<timestamp>.md`, registry, logs, reports |\n\nPractical language:\n\n```text\nA pane is where work is visible.\nA session is what work belongs to.\nA receipt is what makes work resumable.\n```\n\n## cmux vs tmux\n\n`cmux` and `tmux` solve different layers.\n\n| Tool | Role | Use It For |\n| --- | --- | --- |\n| `cmux` | GUI/socket/workspace orchestrator | workspaces, panes, surfaces, browser/editor panels, focused context, keyboard launchers |\n| `tmux` | terminal multiplexer layout primitive | terminal-only layouts, persistent sessions, panes/windows, CLI fanout, `muxai` layouts |\n\nPractical line:\n\n```text\ncmux is the building. tmux is one kind of room layout inside the building.\n```\n\n## Address The Current Context\n\nStart here:\n\n```bash\ncmux identify\n```\n\nLook for:\n\n- `caller`: the surface that invoked the command\n- `focused`: the surface cmux believes is focused\n- `workspace_ref`: project/workspace target\n- `pane_ref`: visible split target\n- `surface_ref`: addressable surface target\n- `tab_ref`: human-facing tab target\n- `socket_path`: socket used by local automation\n\nFor keyboard launchers, prefer the caller surface when present:\n\n```text\n.caller.surface_ref // .focused.surface_ref\n```\n\nThis prevents a shortcut from accidentally targeting a different visible pane.\n\n## Get The Current Workspace Correctly\n\nUse:\n\n```bash\ncmux rpc workspace.current\n```\n\nLook for:\n\n- `workspace.current_directory`\n- `workspace_id`\n- `window_id`\n\nDo not assume this works:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nObserved failure shape:\n\n```text\nError: Invalid workspace handle: current (expected UUID, ref like workspace:1, or index)\n```\n\nRule:\n\n```text\n\"Current\" is a question, not a workspace handle.\nAsk cmux for current state, then use the returned explicit ref/id.\n```\n\n## Know The cmux Environment Variables\n\nInside cmux terminal surfaces, scripts can use:\n\n```text\nCMUX_SURFACE_ID\nCMUX_WORKSPACE_ID\nCMUX_TAB_ID\nCMUX_SOCKET_PATH\n```\n\nQuick check:\n\n```bash\nprintf 'surface=%s\\nworkspace=%s\\ntab=%s\\nsocket=%s\\n' \\\n  \"$CMUX_SURFACE_ID\" \"$CMUX_WORKSPACE_ID\" \"$CMUX_TAB_ID\" \"$CMUX_SOCKET_PATH\"\n```\n\nIf those values are empty, you may not be inside a cmux terminal surface, or the process may not have inherited the cmux environment.\n\n## Create A Helper Pane\n\nShortcut:\n\n```text\ncmux-run-surface \"command\"\n```\n\nRight split:\n\n```bash\ncmux-run-surface \"pwd; echo surface=$CMUX_SURFACE_ID\"\n```\n\nBelow split:\n\n```bash\ncmux-run-surface --below \"pwd; echo surface=$CMUX_SURFACE_ID\"\n```\n\nWhat the launcher does:\n\n```text\ncmux rpc workspace.current\n-> cmux rpc pane.create\n-> cmux rpc pane.surfaces\n-> cmux send \"<command>\"\n-> cmux send-key enter\n```\n\nHow to know it worked:\n\n- a new cmux pane appears\n- the command text is visible in that pane\n- Enter was submitted\n- the command runs from the focused workspace cwd\n- `CMUX_SURFACE_ID` is set inside the new terminal\n\n## Focus Or Open A Project Workspace\n\nShortcut:\n\n```text\ncmux-focus-or-open-workspace /path/to/project\n```\n\nUse this when the problem starts with a directory or repo, not with a visible pane.\n\nWhat the launcher should do:\n\n```text\nfind existing cmux workspace for the project\n-> focus it if it exists\n-> open a new workspace if it does not\n-> keep later helper panes and forks anchored to that project cwd\n```\n\nHow to know it worked:\n\n```bash\ncmux rpc workspace.current\n```\n\nLook for the expected project directory in `workspace.current_directory` before launching helper panes or agent chains.\n\n## Fork The Focused Codex Session\n\nShortcut:\n\n```text\nEsc+P\n```\n\nActual route:\n\n```text\nEsc+P\n-> cmux-fork-focused-codex --preflight-fork\n-> cmux identify\n-> caller/focused surface\n-> cmux rpc pane.surfaces\n-> stable surface id\n-> cmux-codex-session-registry.py --resolve-surface\n-> Codex session id\n-> CODEX_FORK_SESSION_ID=<session-id> p-f\n-> cmux-run-surface\n-> new pane\n```\n\nDry-run first:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nCompact fork below:\n\n```bash\ncmux-fork-focused-codex --dry-run --below --preflight-compact\n```\n\nShortcut mapping:\n\n| Shortcut | Route |\n| --- | --- |\n| `Esc+P` | focused Codex session -> `p-f` |\n| `Esc+Shift+P` | focused Codex session -> compact -> `p-c` below |\n| `Esc+E` | export focused workspace transcript with `cmux-xport` |\n| `Esc+M` | export transcript and open markdown |\n\nWhy this matters:\n\n```text\nfork --last is not the same as fork the conversation in the focused pane.\n```\n\n## Stable Surface IDs And The Registry\n\nShort refs such as `surface:38` are useful in current output, but they are not the durable routing key.\n\nFocused fork should normalize the short surface ref through:\n\n```bash\ncmux rpc pane.surfaces '{\"pane_id\":\"pane:<id>\",\"workspace_id\":\"workspace:<id>\",\"window_id\":\"window:<id>\"}'\n```\n\nThen resolve the Codex session through:\n\n```bash\npython3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" \\\n  --resolve-surface \"surface:<stable-surface-id>\"\n```\n\nScreen fallback exists, but should be fallback only:\n\n```bash\npython3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" \\\n  --resolve-surface \"surface:<id>\" --allow-screen\n```\n\n## Export A Transcript\n\nShortcut:\n\n```text\nEsc+E\n```\n\nCommand:\n\n```bash\ncmux-xport\n```\n\nRoute:\n\n```text\ncmux-xport\n-> cmux rpc workspace.current\n-> cd focused workspace cwd\n-> CODEX_XPORT_SAVE_CWD=1\n-> source ~/.config/zsh/conf.d/40-ai.zsh\n-> xport\n-> clipboard\n-> .exports/<timestamp>.md\n-> notification\n```\n\nHow to know it worked:\n\n```bash\nls -lt .exports | head\ntest -s \"$(ls -t .exports/*.md | head -1)\" && echo export:OK\n```\n\nPractical line:\n\n```text\nClipboard is convenience. .exports is the durable receipt.\n```\n\n## How Helpers Connect To Routing\n\nFirst identify whether the helper is a zsh function, alias, executable, or environment variable.\n\nThen route it to the workspace, pane, surface, or session where it should run.\n\nCommon bridge helpers:\n\n| Helper | What It Does Here |\n| --- | --- |\n| `xfl` | find the Codex session or thread you intend to work with |\n| `xfc` | continue or fork from the chosen Codex context |\n| `xport` | export a Codex conversation from the current project cwd |\n| `p-f` | launch a forked Codex path after the target session is known |\n| `p-c` | launch a compacted Codex path after the target session is known |\n\nIf 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.\n\n## tmux Layouts And Agent Chains\n\nValidate `muxai`:\n\n```zsh\nzsh -ic 'whence -w muxai; funcwhere muxai'\n```\n\nUse `muxai` when you want a terminal-only multi-agent room inside a surface.\n\nValidate `agent_chain`:\n\n```zsh\nzsh -ic 'whence -w agent_chain; funcwhere agent_chain'\n```\n\nUse it for software work where you want phase separation:\n\n```zsh\nagent_chain \"Explore the billing webhook duplicate-processing bug, plan the smallest safe patch, then implement only if tests can verify it.\"\n```\n\nGood uses:\n\n- refactor with a real review gate\n- bug investigation before edit\n- small feature with a plan checkpoint\n- risky implementation that needs a danger confirmation\n\nBad use:\n\n```text\nagent_chain \"fix everything\"\n```\n\n## Ask The Agent This\n\nRoute a helper pane:\n\n```text\nUse the cmux orchestrator source files.\n\nOpen a helper pane for this software project. It should run from the focused\nworkspace cwd and inspect the checkout flow failure without editing files.\nUse cmux routing, not manual terminal instructions. Tell me how to confirm the\npane was created and where to check logs if it fails.\n```\n\nDebug a wrong focused fork:\n\n```text\nEsc+P forked the wrong Codex conversation.\n\nInspect the focused-fork route: `cmux identify`, caller versus focused surface,\n`cmux rpc pane.surfaces`, stable surface lookup, the Codex cmux registry,\n`CODEX_FORK_SESSION_ID`, and the `p-f` handoff. Do not assume `fork --last` is\ncorrect. Give me the dry-run command that proves the target session id before\nlaunching.\n```\n\nExport a conversation:\n\n```text\nExport the focused Codex conversation for this project.\n\nUse `cmux-xport` or the equivalent `CODEX_XPORT_SAVE_CWD=1` zsh path. Confirm\nthe export was copied to the clipboard and saved under `.exports`. Do not paste\nthe whole transcript back into chat.\n```\n\n## What To Confirm / How To Know It Worked\n\n| Goal | Confirmation |\n| --- | --- |\n| Identify current context | `cmux identify` shows caller/focused workspace, pane, surface, tab |\n| Get current workspace | `cmux rpc workspace.current` shows cwd, workspace id, window id |\n| Avoid fake current handle | no command depends on `--workspace current` |\n| Create helper pane | `cmux-run-surface \"echo ok\"` opens a pane and runs from intended cwd |\n| Route focused fork | dry-run prints `CODEX_FORK_SESSION_ID=<uuid> p-f` or `p-c` |\n| Export transcript | `.exports/<timestamp>.md` exists and is non-empty |\n| tmux layout present | `tmux ls` and `tmux list-panes -a` show expected panes |\n| agent chain scoped | goal names a specific software bug or feature and verification command |\n\n## If It Goes Wrong\n\n### Invalid Workspace Handle\n\nBad:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nCorrect:\n\n```bash\ncmux identify\ncmux rpc workspace.current\ncmux rpc workspace.list\n```\n\n### Wrong Session Fork\n\nDry-run:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nCorrect route:\n\n```text\nfocused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID\n```\n\n### Missing `.exports`\n\nCheck:\n\n```bash\nls -lt .exports | head\n```\n\nDirect save shape:\n\n```zsh\nCODEX_XPORT_SAVE_CWD=1 zsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; xport'\n```\n\n### Function Not Found\n\nCheck:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport'\n```\n\nSome orchestration commands are zsh functions. Launch them through zsh or provide executable wrappers.\n\n## References And Resources\n\n- Common cmux config: `~/.config/cmux/cmux.json`\n- Common pane launcher: `~/.local/bin/cmux-run-surface`\n- Common focused fork launcher: `~/.local/bin/cmux-fork-focused-codex`\n- Common xport launcher: `~/.local/bin/cmux-xport`\n- Common registry hook: `~/.codex/hooks/cmux-codex-session-registry.py`\n- Common tmux helper source: `~/.config/zsh/conf.d/18-tmux-zle-dsl.zsh`\n- Common agent chain source: `~/.config/zsh/conf.d/47-ai-pipeline-agent-chain-dsl.zsh`\n- tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html\n- tmux GitHub wiki: https://github.com/tmux/tmux/wiki\n- OpenAI Codex: https://openai.com/codex/\n- Model Context Protocol: https://modelcontextprotocol.io/\n- Zsh manual, Shell Builtin Commands: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
