{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-workspace-routing-practice",
  "slug": "workspace-routing-practice",
  "title": "Workspace and session routing: practice drills",
  "summary": "Nine exercises establish workspace-to-session routing and receipts using cmux identity, explicit handles, workspace focus, environment inspection, helper panes, focused Codex fork previews, transcript exports, layered debugging, and gated agent_chain phases.",
  "category": "Execution",
  "tags": [
    "cmux",
    "tmux",
    "orchestration",
    "practice"
  ],
  "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!/exercises/04-agentic-dev-environment-orchestrator.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 1: Address The Current Work",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 2: Prove The `current` Handle Failure",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 3: Focus Or Open A Workspace",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 4: Capture The cmux Environment",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 5: Open A Safe Helper Pane",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 6: Dry-Run A Focused Codex Fork",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 7: Export A Transcript",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 8: Decide Whether It Is cmux Or tmux",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/exercises/04-agentic-dev-environment-orchestrator.md#Exercises: 04. Agentic Dev Environment / Orchestrator/Exercise 9: Design A Gated `agent_chain` Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "execution",
  "wordCount": 724,
  "url": "/topics/codex-workspace-routing-practice/",
  "markdownUrl": "/markdown/codex-workspace-routing-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-workspace-routing-practice.json",
  "headings": [
    {
      "id": "exercise-1-address-the-current-work",
      "text": "Exercise 1: Address The Current Work",
      "level": 2
    },
    {
      "id": "exercise-2-prove-the-current-handle-failure",
      "text": "Exercise 2: Prove The `current` Handle Failure",
      "level": 2
    },
    {
      "id": "exercise-3-focus-or-open-a-workspace",
      "text": "Exercise 3: Focus Or Open A Workspace",
      "level": 2
    },
    {
      "id": "exercise-4-capture-the-cmux-environment",
      "text": "Exercise 4: Capture The cmux Environment",
      "level": 2
    },
    {
      "id": "exercise-5-open-a-safe-helper-pane",
      "text": "Exercise 5: Open A Safe Helper Pane",
      "level": 2
    },
    {
      "id": "exercise-6-dry-run-a-focused-codex-fork",
      "text": "Exercise 6: Dry-Run A Focused Codex Fork",
      "level": 2
    },
    {
      "id": "exercise-7-export-a-transcript",
      "text": "Exercise 7: Export A Transcript",
      "level": 2
    },
    {
      "id": "exercise-8-decide-whether-it-is-cmux-or-tmux",
      "text": "Exercise 8: Decide Whether It Is cmux Or tmux",
      "level": 2
    },
    {
      "id": "exercise-9-design-a-gated-agent-chain-goal",
      "text": "Exercise 9: Design A Gated `agent_chain` Goal",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Workspace and session routing: practice drills\n\nThese exercises practice routing work through the agentic dev environment.\n\nThe goal is to prove:\n\n```text\nworkspace -> pane -> surface/tab -> process/session -> receipt\n```\n\nUse a real software project directory when possible. Prefer dry-runs before launching anything.\n\n## Exercise 1: Address The Current Work\n\nRun:\n\n```bash\ncmux identify\ncmux rpc workspace.current\n```\n\nFill out:\n\n```markdown\n# cmux Address Notes\n\n- workspace_ref:\n- workspace_id:\n- workspace cwd:\n- window_id:\n- pane_ref:\n- surface_ref:\n- tab_ref:\n- surface_type:\n- caller/focused same? yes/no\n- command that should target this surface:\n```\n\n## Exercise 2: Prove The `current` Handle Failure\n\nRun:\n\n```bash\ncmux top --workspace current --processes --flat --format tsv\n```\n\nThen run:\n\n```bash\ncmux rpc workspace.current\n```\n\nFill out:\n\n```markdown\n# Workspace Handle Notes\n\n- failed command:\n- exact error:\n- correct command:\n- returned workspace id/ref:\n- returned cwd:\n- lesson:\n```\n\nExpected lesson:\n\n```text\n`current` is not a workspace handle. Ask cmux for current state, then use explicit refs or ids.\n```\n\n## Exercise 3: Focus Or Open A Workspace\n\nChoose a software project directory and run:\n\n```bash\ncmux-focus-or-open-workspace /path/to/project\ncmux rpc workspace.current\n```\n\nFill out:\n\n```markdown\n# Workspace Focus Notes\n\n- project path:\n- did cmux focus an existing workspace or open a new one:\n- workspace cwd:\n- workspace id/ref:\n- next command that should run from this cwd:\n```\n\n## Exercise 4: Capture The cmux Environment\n\nInside a cmux terminal, run:\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\nFill out:\n\n```markdown\n# cmux Env Notes\n\n- CMUX_SURFACE_ID:\n- CMUX_WORKSPACE_ID:\n- CMUX_TAB_ID:\n- CMUX_SOCKET_PATH:\n- which value identifies the smallest routing target:\n- which value would a registry hook need:\n- which value helps external automation talk to cmux:\n```\n\n## Exercise 5: Open A Safe Helper Pane\n\nRun:\n\n```bash\ncmux-run-surface 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK'\n```\n\nOptional below split:\n\n```bash\ncmux-run-surface --below 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK'\n```\n\nFill out:\n\n```markdown\n# Helper Pane Notes\n\n- command:\n- right or below:\n- did a new pane open? yes/no\n- cwd printed:\n- surface id printed:\n- did the command submit automatically? yes/no\n- if failed, log checked:\n```\n\n## Exercise 6: Dry-Run A Focused Codex Fork\n\nFocus a cmux pane that has a Codex conversation.\n\nRun:\n\n```bash\ncmux-fork-focused-codex --dry-run --preflight-fork\n```\n\nThen run:\n\n```bash\ncmux-fork-focused-codex --dry-run --below --preflight-compact\n```\n\nFill out:\n\n```markdown\n# Focused Fork Notes\n\n- fork command output:\n- compact command output:\n- includes CODEX_FORK_SESSION_ID? yes/no\n- launches `p-f` or `p-c`?\n- target session id:\n- why this is safer than `fork --last`:\n```\n\n## Exercise 7: Export A Transcript\n\nRun:\n\n```bash\ncmux-xport\nls -lt .exports | head\n```\n\nThen verify latest export is non-empty:\n\n```bash\nlatest=\"$(ls -t .exports/*.md 2>/dev/null | head -1)\"\ntest -n \"$latest\" && test -s \"$latest\" && echo \"export:OK $latest\" || echo \"export:MISSING\"\n```\n\nFill out:\n\n```markdown\n# xport Notes\n\n- command:\n- workspace cwd:\n- latest export file:\n- file exists? yes/no\n- file non-empty? yes/no\n- what this export can prove later:\n```\n\n## Exercise 8: Decide Whether It Is cmux Or tmux\n\nFor each failure, choose `cmux`, `tmux`, `zsh`, or `Codex registry`.\n\n| Failure | Layer |\n| --- | --- |\n| `cmux identify` cannot connect to socket | |\n| `cmux-run-surface` cannot create a pane | |\n| `muxai` creates a weird tiled layout | |\n| `p-f: command not found` | |\n| `Esc+P` targets the wrong Codex UUID | |\n| `.exports` is missing after xport | |\n| `tmux ls` shows no expected session | |\n| `CMUX_SURFACE_ID` is empty inside a hook | |\n\nUseful commands:\n\n```bash\ncmux identify\ncmux rpc workspace.current\ntmux ls\ntmux list-panes -a\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\"; whence -w p-f p-c xport'\npython3 \"$HOME/.codex/hooks/cmux-codex-session-registry.py\" --registry-path\n```\n\n## Exercise 9: Design A Gated `agent_chain` Goal\n\nBad:\n\n```text\nfix everything\n```\n\nBetter template:\n\n```text\nExplore <specific bug or feature>, plan the smallest safe patch, then implement\nonly if <verification command> can prove it.\n```\n\nWrite your goal:\n\n```markdown\n# agent_chain Goal\n\nagent_chain \"<goal>\"\n```\n\nFill out expected reports:\n\n```markdown\n# Expected Phase Receipts\n\n## Explore\n\n- files inspected:\n- hypothesis:\n- risks:\n\n## Plan\n\n- smallest patch:\n- tests:\n- rollback:\n\n## Implement\n\n- files changed:\n- verification command:\n- result:\n```\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/)"
}
