Team Learning Goal
Teach focused routing, not terminal window management.
The audience should understand workspace -> pane -> surface/tab -> process/session -> receipt, and should be able to explain why shortcuts must route to the focused surface and correct Codex session.
Walkthrough Depth
Essential Walkthrough
- Draw
workspace -> pane -> surface/tab -> process/session -> receipt. - Run
cmux identify. - Run
cmux rpc workspace.current. - Show the invalid
--workspace currentfailure. - Dry-run
cmux-fork-focused-codex --preflight-fork. - Show
cmux-xportand.exports.
Expanded Walkthrough
Add:
cmux-run-surface- stable surface lookup
- registry resolution
Esc+P,Esc+Shift+P,Esc+E,Esc+Mmuxaiversusagent_chain
Deep-Dive Walkthrough
Add:
- workspace focus/open dry-run
- screen fallback caveat
- helper function visibility for
xfl,xfc,xport,p-f,p-c - exercises
Talking Points
Opening:
Focused context is a routing problem, not a prompt problem.
On the graph:
A pane is where work is visible. A session is what work belongs to. A receipt is what makes work resumable.
On cmux vs tmux:
cmux is the building. tmux is one kind of room layout inside the building.
On focused forks:
Esc+Pis not just a shortcut. It is a session-routing pipeline.
On exports:
Clipboard is convenience.
.exportsis the durable receipt.
Essential Points To Preserve
Preserve:
cmux identify
cmux rpc workspace.current
cmux-focus-or-open-workspace /path/to/project
cmux-run-surface "echo ok"
cmux-fork-focused-codex --dry-run --preflight-fork
cmux-xport
Preserve this route:
focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID -> p-f / p-c
Failure Paths To Preserve
Invalid workspace handle:
cmux top --workspace current --processes --flat --format tsv
Wrong session fork:
cmux-fork-focused-codex --dry-run --preflight-fork
Missing export:
ls -lt .exports | head
Function not found:
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh"; whence -w p-f p-c xport'
Boundaries
Section 3 is about helper names and zsh runtime shape. Section 4 is about where those helpers run.
| Section 3 | Section 4 |
|---|---|
| Is this a function, alias, or executable? | Which pane/surface/session does it target? |
whence -w |
cmux identify |
type, functions, funcwhere |
workspace.current, pane.surfaces |
| zsh helper loading | cmux socket routing |
| executable fallbacks | new panes, focused session forks, exports |
Section 5 builds the preflight prompt before a routed fork runs.
Further References
- team member cheatsheet:
cheatsheets/04-agentic-dev-environment-orchestrator.md - Exercises:
exercises/04-agentic-dev-environment-orchestrator.md - tmux manual page: https://man7.org/linux/man-pages/man1/tmux.1.html
- tmux GitHub wiki: https://github.com/tmux/tmux/wiki
- OpenAI Codex: https://openai.com/codex/
- Model Context Protocol: https://modelcontextprotocol.io/