---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-workspace-routing-team-guide"
title: "Workspace and session routing: team walkthrough"
---

# Workspace and session routing: team walkthrough

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

1. Draw `workspace -> pane -> surface/tab -> process/session -> receipt`.
2. Run `cmux identify`.
3. Run `cmux rpc workspace.current`.
4. Show the invalid `--workspace current` failure.
5. Dry-run `cmux-fork-focused-codex --preflight-fork`.
6. Show `cmux-xport` and `.exports`.

### Expanded Walkthrough

Add:

- `cmux-run-surface`
- stable surface lookup
- registry resolution
- `Esc+P`, `Esc+Shift+P`, `Esc+E`, `Esc+M`
- `muxai` versus `agent_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+P` is not just a shortcut. It is a session-routing pipeline.

On exports:

> Clipboard is convenience. `.exports` is the durable receipt.

## Essential Points To Preserve

Preserve:

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

```text
focused surface -> stable surface -> registry -> session id -> CODEX_FORK_SESSION_ID -> p-f / p-c
```

## Failure Paths To Preserve

Invalid workspace handle:

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

Wrong session fork:

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

Missing export:

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

Function not found:

```zsh
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/

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