Workspace and session routing: practice drills

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.

These exercises practice routing work through the agentic dev environment.

The goal is to prove:

workspace -> pane -> surface/tab -> process/session -> receipt

Use a real software project directory when possible. Prefer dry-runs before launching anything.

Exercise 1: Address The Current Work

Run:

cmux identify
cmux rpc workspace.current

Fill out:

# cmux Address Notes

- workspace_ref:
- workspace_id:
- workspace cwd:
- window_id:
- pane_ref:
- surface_ref:
- tab_ref:
- surface_type:
- caller/focused same? yes/no
- command that should target this surface:

Exercise 2: Prove The current Handle Failure

Run:

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

Then run:

cmux rpc workspace.current

Fill out:

# Workspace Handle Notes

- failed command:
- exact error:
- correct command:
- returned workspace id/ref:
- returned cwd:
- lesson:

Expected lesson:

`current` is not a workspace handle. Ask cmux for current state, then use explicit refs or ids.

Exercise 3: Focus Or Open A Workspace

Choose a software project directory and run:

cmux-focus-or-open-workspace /path/to/project
cmux rpc workspace.current

Fill out:

# Workspace Focus Notes

- project path:
- did cmux focus an existing workspace or open a new one:
- workspace cwd:
- workspace id/ref:
- next command that should run from this cwd:

Exercise 4: Capture The cmux Environment

Inside a cmux terminal, run:

printf 'surface=%s\nworkspace=%s\ntab=%s\nsocket=%s\n' \
  "$CMUX_SURFACE_ID" "$CMUX_WORKSPACE_ID" "$CMUX_TAB_ID" "$CMUX_SOCKET_PATH"

Fill out:

# cmux Env Notes

- CMUX_SURFACE_ID:
- CMUX_WORKSPACE_ID:
- CMUX_TAB_ID:
- CMUX_SOCKET_PATH:
- which value identifies the smallest routing target:
- which value would a registry hook need:
- which value helps external automation talk to cmux:

Exercise 5: Open A Safe Helper Pane

Run:

cmux-run-surface 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK'

Optional below split:

cmux-run-surface --below 'pwd; echo CMUX_SURFACE_ID=$CMUX_SURFACE_ID; echo helper-pane:OK'

Fill out:

# Helper Pane Notes

- command:
- right or below:
- did a new pane open? yes/no
- cwd printed:
- surface id printed:
- did the command submit automatically? yes/no
- if failed, log checked:

Exercise 6: Dry-Run A Focused Codex Fork

Focus a cmux pane that has a Codex conversation.

Run:

cmux-fork-focused-codex --dry-run --preflight-fork

Then run:

cmux-fork-focused-codex --dry-run --below --preflight-compact

Fill out:

# Focused Fork Notes

- fork command output:
- compact command output:
- includes CODEX_FORK_SESSION_ID? yes/no
- launches `p-f` or `p-c`?
- target session id:
- why this is safer than `fork --last`:

Exercise 7: Export A Transcript

Run:

cmux-xport
ls -lt .exports | head

Then verify latest export is non-empty:

latest="$(ls -t .exports/*.md 2>/dev/null | head -1)"
test -n "$latest" && test -s "$latest" && echo "export:OK $latest" || echo "export:MISSING"

Fill out:

# xport Notes

- command:
- workspace cwd:
- latest export file:
- file exists? yes/no
- file non-empty? yes/no
- what this export can prove later:

Exercise 8: Decide Whether It Is cmux Or tmux

For each failure, choose cmux, tmux, zsh, or Codex registry.

Failure Layer
cmux identify cannot connect to socket
cmux-run-surface cannot create a pane
muxai creates a weird tiled layout
p-f: command not found
Esc+P targets the wrong Codex UUID
.exports is missing after xport
tmux ls shows no expected session
CMUX_SURFACE_ID is empty inside a hook

Useful commands:

cmux identify
cmux rpc workspace.current
tmux ls
tmux list-panes -a
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport'
python3 "$HOME/.codex/hooks/cmux-codex-session-registry.py" --registry-path

Exercise 9: Design A Gated agent_chain Goal

Bad:

fix everything

Better template:

Explore <specific bug or feature>, plan the smallest safe patch, then implement
only if <verification command> can prove it.

Write your goal:

# agent_chain Goal

agent_chain "<goal>"

Fill out expected reports:

# Expected Phase Receipts

## Explore

- files inspected:
- hypothesis:
- risks:

## Plan

- smallest patch:
- tests:
- rollback:

## Implement

- files changed:
- verification command:
- result:

Source references