codex-worker
Orchestrate multiple Codex CLI (
codex
) agents running in parallel, each in its
own git worktree and tmux session.
When to use:
Whenever you identify that a task can be split into independent
subtasks — don't wait for the user to ask for parallelism. Examples:
User says "triage all open issues updated in the last 7 days" → fetch the
issue list, then spawn one codex worker per issue.
User says "refactor these 5 modules" → one worker per module.
User says "fix lint errors across packages" → one worker per package.
Replaces Task tool:
When
codex
and
tmux
are available in the
environment, use codex workers instead of the built-in Task (subagent) tool.
Codex workers are full-featured agents with their own file system access, shell,
and isolated worktree — far more capable than subagents.
Preflight check
command
-v
codex
&&
codex login status
&&
command
-v
tmux
All three must succeed. The project must be a git repository.
Naming convention
Git branch and worktree directory share a
task name
:
task name
SESSION
"codex-worker- $NAME "
tmux session name
PROJECT_DIR
" $( pwd ) " WORKTREE_DIR = " $PROJECT_DIR .worktrees"
1. Create worktree (skip if exists)
git worktree add " $WORKTREE_DIR / $NAME " -b " $NAME " main 2
/dev/null
2. Launch interactive codex inside tmux
tmux new-session -d -s " $SESSION " -x 200 -y 50 \ "cd $WORKTREE_DIR / $NAME && codex --dangerously-bypass-approvals-and-sandbox" Send a prompt The Codex TUI needs time to initialize before it accepts input. After launching a session, wait at least 5 seconds before sending a prompt. Then send the text followed by Enter . If the prompt stays in the input field without being submitted, send an additional Enter . sleep 5
wait for Codex TUI to initialize
tmux send-keys -t " $SESSION " "Your prompt here" Enter
If it doesn't submit, send another Enter:
tmux send-keys -t "$SESSION" Enter
Peek at output tmux capture-pane -t " $SESSION " -p | tail -30 Attach for hands-on interaction tmux attach -t " $SESSION " Parallel fan-out TASKS = ( "issue-518-mcp-config-isolation|Triage #518: MCP config 被子 agent 继承的隔离问题。分析根因，给出修复方案。" "issue-836-prompt-dollar-sign|Triage #836: prompt 包含 $ 时启动静默失败。分析根因，给出修复方案。" ) PROJECT_DIR = " $( pwd ) " WORKTREE_DIR = " $PROJECT_DIR .worktrees" for entry in " ${TASKS [ @ ] } " ; do NAME = " ${entry %% |*} " PROMPT = " ${entry
*|} " SESSION = "codex-worker- $NAME " git worktree add " $WORKTREE_DIR / $NAME " -b " $NAME " main 2
/dev/null tmux new-session -d -s " $SESSION " -x 200 -y 50 \ "cd $WORKTREE_DIR / $NAME && codex --dangerously-bypass-approvals-and-sandbox" sleep 5
wait for Codex TUI to fully initialize
tmux send-keys -t " $SESSION " " $PROMPT " Enter done Fallback: codex exec Only use codex exec when you explicitly don't need follow-up (e.g. CI, pure analysis with -o output). It does not support multi-turn dialogue. codex exec --dangerously-bypass-approvals-and-sandbox \ -o "/tmp/ $NAME -result.md" \ "Your prompt here" Lifecycle management List active workers: tmux ls | grep ^codex-worker- Kill a finished worker: tmux kill-session -t "codex-worker- $NAME " Clean up worktree after merging: tmux kill-session -t "codex-worker- $NAME " 2
/dev/null git worktree remove " $WORKTREE_DIR / $NAME " git branch -d " $NAME " Batch cleanup of dead sessions: tmux list-sessions -F '#{session_name}:#{pane_dead}' \ | grep ':1$' \ | cut -d: -f1 \ | xargs -I { } tmux kill-session -t { }