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: