名称：codex-worker 描述：通过 tmux 并行生成和管理多个 Codex CLI 代理以处理任务。每当任务可以分解为独立子任务时使用（例如，批量分类、并行修复、多文件重构）。当 codex 和 tmux 可用时，优先使用此工具而非内置的 Task 工具以实现并行性。

codex-worker

编排多个并行运行的 Codex CLI（codex）代理，每个代理在其自己的 git 工作树和 tmux 会话中运行。

何时使用： 每当识别出任务可以拆分为独立子任务时——无需等待用户要求并行性。示例：

用户说“分类所有最近 7 天更新的开放问题”→获取问题列表，然后为每个问题生成一个 codex 工作器。
用户说“重构这 5 个模块”→每个模块一个工作器。
用户说“修复跨包的 lint 错误”→每个包一个工作器。

替换 Task 工具： 当环境中 codex 和 tmux 可用时，使用 codex 工作器替代内置的 Task（子代理）工具。Codex 工作器是具有自己文件系统访问、shell 和隔离工作树的全功能代理，能力远强于子代理。

预检检查

command -v codex && codex login status && command -v tmux

所有三个必须成功。项目必须是 git 仓库。

命名约定

Git 分支和工作树目录共享一个任务名称：

<类型>-<问题编号（可选）>-<简短描述>

tmux 会话添加一个 codex-worker- 前缀，以便轻松筛选工作器：

	格式	示例
任务名称	`<类型>-<编号>-<描述>`	`issue-836-prompt-dollar-sign`
Git 分支	同任务名称	`issue-836-prompt-dollar-sign`
工作树目录	`<项目>.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 工作器：tmux ls | grep ^codex-worker-

用法

优先使用 tmux + 交互式 codex 处理所有任务。它支持多轮对话，用户可以 tmux attach 检查或干预，并且可以从外部发送后续提示。

生成一个工作器

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

# 1. 创建工作树（如果存在则跳过）
git worktree add "$WORKTREE_DIR/$NAME" -b "$NAME" main 2>/dev/null

# 2. 在 tmux 内启动交互式 codex
tmux new-session -d -s "$SESSION" -x 200 -y 50 \
  "cd $WORKTREE_DIR/$NAME && codex --dangerously-bypass-approvals-and-sandbox"

发送提示

Codex TUI 需要时间初始化才能接受输入。启动会话后，至少等待 5 秒再发送提示。然后发送文本后跟 Enter。如果提示停留在输入字段中未被提交，则发送额外的 Enter。

sleep 5  # 等待 Codex TUI 初始化
tmux send-keys -t "$SESSION" "您的提示在此处" Enter
# 如果未提交，发送另一个 Enter：
# tmux send-keys -t "$SESSION" Enter

查看输出

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

附加以进行手动交互

tmux attach -t "$SESSION"

并行扇出

TASKS=(
  "issue-518-mcp-config-isolation|分类 #518：MCP 配置被子代理继承的隔离问题。分析根因，给出修复方案。"
  "issue-836-prompt-dollar-sign|分类 #836：提示包含 $ 时启动静默失败。分析根因，给出修复方案。"
)

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

备选方案：`codex exec`

仅当明确不需要后续交互时使用 codex exec（例如，CI、纯分析并输出 -o）。它不支持多轮对话。

codex exec --dangerously-bypass-approvals-and-sandbox \
  -o "/tmp/$NAME-result.md" \
  "您的提示在此处"

生命周期管理

列出活跃工作器：

tmux ls | grep ^codex-worker-

终止已完成的工作器：

tmux kill-session -t "codex-worker-$NAME"

合并后清理工作树：

tmux kill-session -t "codex-worker-$NAME" 2>/dev/null
git worktree remove "$WORKTREE_DIR/$NAME"
git branch -d "$NAME"

批量清理死会话：

tmux list-sessions -F '#{session_name}:#{pane_dead}' \
  | grep ':1$' \
  | cut -d: -f1 \
  | xargs -I{} tmux kill-session -t {}