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

# Workspace and session routing: practice drills

These exercises practice routing work through the agentic dev environment.

The goal is to prove:

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

```bash
cmux identify
cmux rpc workspace.current
```

Fill out:

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

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

Then run:

```bash
cmux rpc workspace.current
```

Fill out:

```markdown
# Workspace Handle Notes

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

Expected lesson:

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

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

Fill out:

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

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

Fill out:

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

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

Optional below split:

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

Fill out:

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

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

Then run:

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

Fill out:

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

```bash
cmux-xport
ls -lt .exports | head
```

Then verify latest export is non-empty:

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

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

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

```text
fix everything
```

Better template:

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

Write your goal:

```markdown
# agent_chain Goal

agent_chain "<goal>"
```

Fill out expected reports:

```markdown
# Expected Phase Receipts

## Explore

- files inspected:
- hypothesis:
- risks:

## Plan

- smallest patch:
- tests:
- rollback:

## Implement

- files changed:
- verification command:
- result:
```

## 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)
