cmux Codex Worktree

Launch visible child Codex TUI panes in cmux for parallel git worktree development.

This skill is meant for situations where parallel work should remain observable. Instead of spawning hidden background agents, it helps a coordinating Codex session split work into explicit lanes, create or reuse git worktrees, and launch one child Codex TUI per lane in cmux.

Contents

• SKILL.md - Skill instructions for coordinating parallel work.
• scripts/launch-child-codex.sh - Helper that opens a cmux pane and starts Codex with a lane prompt.
• agents/openai.yaml - Display metadata for the skill.

Requirements

• cmux available in PATH
• codex available in PATH
• git worktrees for isolated lane work
• base64, available by default on macOS and most Linux distributions
• A reachable cmux socket, verified by cmux ping

Usage

Use the skill from a coordinating Codex session when the user asks for concurrent worktrees, visible child Codex panes, cmux split panes, or observable parallel lanes.

Before launching children, define each lane:

• lane name
• worktree path
• branch name
• owned files
• forbidden files or directories
• validation commands
• handoff conditions

Then launch a visible child Codex pane with the bundled helper:

scripts/launch-child-codex.sh \
  --cwd /absolute/worktree/path \
  --name lane-name \
  --prompt "Implement the lane-specific task, validate it, and report completion." \
  --direction right

The helper opens a new cmux pane, sends the Codex command into it, and prints the created surface, pane, lane name, and cwd.

Helper Options

--cwd <path>              Absolute or relative working directory for child Codex.
--prompt <text>           Prompt passed to child Codex.
--name <lane>             Lane name printed in the child pane. Defaults to child-codex.
--direction <direction>   cmux split direction: right, left, up, or down. Defaults to right.
--focus <true|false>      Whether the new cmux pane should receive focus. Defaults to false.
--extra-codex-arg <arg>   Additional argument forwarded to codex. Can be repeated.

Monitoring

Use cmux to inspect or steer child panes:

cmux read-screen --surface surface:2 --lines 120
cmux send --surface surface:2 -- "status update requested\n"
cmux send-key --surface surface:2 C-c

Use cmux tree or cmux list-panes when the surface reference is unclear.

Safety Model

• Keep every lane's ownership boundary explicit before launch.
• Prefer normal non-destructive git commands for creating or reusing worktrees.
• Do not let a child lane edit coordinator-only files unless that is part of its assigned scope.
• Review child commits from the coordinator worktree before merging.
• If cmux is unavailable, print exact commands for the user instead of silently switching to another terminal multiplexer.

Troubleshooting

• cmux not found in PATH: Install or expose cmux before using this skill.
• codex not found in PATH: Install or expose the Codex CLI before launching a child lane.
• cmux socket is not reachable: Start or reconnect to cmux, then confirm cmux ping succeeds.
• Missing cwd: Create the worktree or pass the correct lane directory.
• Invalid --direction: Use one of right, left, up, or down.