Back to Details

codex-worker

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

codex-worker

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.
协调多个Codex CLI（
codex
）Agent并行运行，每个Agent都在独立的git worktree和tmux会话中。
适用场景： 当你发现任务可拆分为独立子任务时即可使用——无需等待用户要求并行处理。示例：
  • 用户要求“分类过去7天更新的所有未解决问题” → 获取问题列表，然后为每个问题生成一个codex worker。
  • 用户要求“重构这5个模块” → 为每个模块分配一个worker。
  • 用户要求“修复各包中的lint错误” → 为每个包分配一个worker。
替代Task工具： 当环境中存在
codex
和
tmux
时，使用codex workers替代内置的Task（子Agent）工具。Codex workers是功能完整的Agent，拥有独立的文件系统访问权限、shell和隔离的worktree——功能远胜于子Agent。

Preflight check

预检检查

bash
command -v codex && codex login status && command -v tmux
All three must succeed. The project must be a git repository.
bash
command -v codex && codex login status && command -v tmux
以上三个命令必须全部执行成功。项目必须是git仓库。

Naming convention

命名规范

Git branch and worktree directory share a task name:
<type>-<issue number (optional)>-<short description>
The tmux session adds a 
codex-worker-
prefix so workers are easy to filter:
FormatExample
Task name
<type>-<number>-<desc>
issue-836-prompt-dollar-sign
Git branchsame as task name
issue-836-prompt-dollar-sign
Worktree dir
<project>.worktrees/<task>
kimi-cli.worktrees/issue-836-prompt-dollar-sign
tmux session
codex-worker-<task>
codex-worker-issue-836-prompt-dollar-sign
More examples:
  • issue-518-mcp-config-isolation
  • fix-share-dir-skills-path
  • feat-ask-user-tool
  • refactor-jinja-templates
List only codex workers: 
tmux ls | grep ^codex-worker-
Git分支和worktree目录共享同一个任务名称：
<类型>-<问题编号（可选）>-<简短描述>
tmux会话会添加
codex-worker-
前缀，以便于筛选workers：
格式示例
任务名称
<类型>-<编号>-<描述>
issue-836-prompt-dollar-sign
Git分支与任务名称相同
issue-836-prompt-dollar-sign
Worktree目录
<项目名>.worktrees/<任务名称>
kimi-cli.worktrees/issue-836-prompt-dollar-sign
tmux会话
codex-worker-<任务名称>
codex-worker-issue-836-prompt-dollar-sign
更多示例：
  • issue-518-mcp-config-isolation
  • fix-share-dir-skills-path
  • feat-ask-user-tool
  • refactor-jinja-templates
仅列出codex workers：
tmux ls | grep ^codex-worker-

Usage

使用方法

Prefer tmux + interactive codex for all tasks. It supports multi-turn dialogue, the user can 
tmux attach
to inspect or intervene, and you can send follow-up prompts from outside.
优先使用tmux + 交互式codex处理所有任务。它支持多轮对话，用户可通过
tmux attach
查看或干预，你也可以从外部发送后续提示。

Spawn a worker

生成worker

bash
NAME="issue-836-prompt-dollar-sign"        # task name
SESSION="codex-worker-$NAME"               # tmux session name
PROJECT_DIR="$(pwd)"
WORKTREE_DIR="$PROJECT_DIR.worktrees"
bash
NAME="issue-836-prompt-dollar-sign"        # 任务名称
SESSION="codex-worker-$NAME"               # tmux会话名称
PROJECT_DIR="$(pwd)"
WORKTREE_DIR="$PROJECT_DIR.worktrees"

1. Create worktree (skip if exists)

1. 创建worktree（若已存在则跳过）

git worktree add "$WORKTREE_DIR/$NAME" -b "$NAME" main 2>/dev/null
git worktree add "$WORKTREE_DIR/$NAME" -b "$NAME" main 2>/dev/null

2. Launch interactive codex inside tmux

2. 在tmux中启动交互式codex

tmux new-session -d -s "$SESSION" -x 200 -y 50
"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox"
undefined
tmux new-session -d -s "$SESSION" -x 200 -y 50
"cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox"
undefined

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
.
bash
sleep 5  # wait for Codex TUI to initialize
tmux send-keys -t "$SESSION" "Your prompt here" Enter
Codex TUI需要时间初始化才能接受输入。启动会话后，至少等待5秒再发送提示。然后发送文本并按
Enter
。如果提示停留在输入框未提交，可再按一次
Enter
。
bash
sleep 5  # 等待Codex TUI初始化
tmux send-keys -t "$SESSION" "你的提示内容" Enter

If it doesn't submit, send another Enter:

如果未提交，再发送一次Enter：

tmux send-keys -t "$SESSION" Enter

tmux send-keys -t "$SESSION" Enter

undefined
undefined

Peek at output

查看输出

bash
tmux capture-pane -t "$SESSION" -p | tail -30
bash
tmux capture-pane -t "$SESSION" -p | tail -30

Attach for hands-on interaction

连接会话进行手动交互

bash
tmux attach -t "$SESSION"
bash
tmux attach -t "$SESSION"

Parallel fan-out

并行扩展

bash
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
bash
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  # 等待Codex TUI完全初始化
  tmux send-keys -t "$SESSION" "$PROMPT" Enter
done

Fallback: 
codex exec

备选方案：
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.
bash
codex exec --dangerously-bypass-approvals-and-sandbox \
  -o "/tmp/$NAME-result.md" \
  "Your prompt here"
仅当明确无需后续交互时使用
codex exec
（例如CI、带
-o
输出的纯分析任务）。它不支持多轮对话。
bash
codex exec --dangerously-bypass-approvals-and-sandbox \
  -o "/tmp/$NAME-result.md" \
  "你的提示内容"

Lifecycle management

生命周期管理

List active workers:
bash
tmux ls | grep ^codex-worker-
Kill a finished worker:
bash
tmux kill-session -t "codex-worker-$NAME"
Clean up worktree after merging:
bash
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:
bash
tmux list-sessions -F '#{session_name}:#{pane_dead}' \
  | grep ':1$' \
  | cut -d: -f1 \
  | xargs -I{} tmux kill-session -t {}
列出活跃的workers：
bash
tmux ls | grep ^codex-worker-
终止已完成的worker：
bash
tmux kill-session -t "codex-worker-$NAME"
合并后清理worktree：
bash
tmux kill-session -t "codex-worker-$NAME" 2>/dev/null
git worktree remove "$WORKTREE_DIR/$NAME"
git branch -d "$NAME"
批量清理已终止的会话：
bash
tmux list-sessions -F '#{session_name}:#{pane_dead}' \
  | grep ':1$' \
  | cut -d: -f1 \
  | xargs -I{} tmux kill-session -t {}