codex-worker

codex-worker

複数の Codex CLI（codex）エージェントを並列でオーケストレーションします。それぞれが独自の git worktree と tmux セッションで実行されます。

使用するタイミング： タスクを独立したサブタスクに分割できると判断したら、いつでも使用してください。ユーザーから並列処理を依頼されるまで待つ必要はありません。例：

• ユーザーが「過去 7 日間に更新されたすべての未解決 issue をトリアージして」と依頼 → issue の一覧を取得し、issue ごとに codex worker を起動します。
• ユーザーが「この 5 つのモジュールをリファクタリングして」と依頼 → モジュールごとに worker を 1 つ起動します。
• ユーザーが「パッケージ全体の lint エラーを修正して」と依頼 → パッケージごとに worker を 1 つ起動します。

Task ツールの代替： 環境で codex と tmux が利用できる場合は、組み込みの Task（サブエージェント）ツールの代わりに codex worker を使用してください。Codex worker は、独自のファイルシステムアクセス、シェル、分離された worktree を備えたフル機能のエージェントであり、サブエージェントよりはるかに高機能です。

起動前の確認

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

3 つすべてが成功する必要があります。プロジェクトは git リポジトリでなければなりません。

命名規則

Git ブランチと worktree ディレクトリでは、タスク名を共通で使用します。

<type>-<issue number (optional)>-<short description>

tmux セッションには codex-worker- というプレフィックスを付けるため、worker を簡単に絞り込めます。

	形式	例
タスク名	<type>-<number>-<desc>	issue-836-prompt-dollar-sign
Git ブランチ	タスク名と同じ	issue-836-prompt-dollar-sign
Worktree ディレクトリ	<project>.worktrees/<task>	kimi-cli.worktrees/issue-836-prompt-dollar-sign
tmux セッション	codex-worker-<task>	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 worker のみを一覧表示します：tmux ls | grep ^codex-worker-

使用方法

すべてのタスクで tmux と対話型 codex の使用を推奨します。複数ターンの対話に対応しており、ユーザーは tmux attach で確認や介入ができ、外部から追加のプロンプトを送信することもできます。

Worker の起動

NAME="issue-836-prompt-dollar-sign"        # 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"

プロンプトの送信

Codex TUI が入力を受け付けるようになるまで、初期化に時間がかかります。 セッションの起動後、プロンプトを送信する前に少なくとも 5 秒待ってください。その後、テキストを送信してから Enter を押します。プロンプトが送信されず入力欄に残っている場合は、もう一度 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

出力の確認

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

接続して手動で操作

tmux attach -t "$SESSION"

並列での分散起動

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

代替手段：codex exec

追加のやり取りが明らかに不要な場合（CI や -o で出力する純粋な分析など）に限り、codex exec を使用してください。複数ターンの対話には対応していません。

codex exec --dangerously-bypass-approvals-and-sandbox \
  -o "/tmp/$NAME-result.md" \
  "Your prompt here"

ライフサイクル管理

アクティブな worker を一覧表示します：

tmux ls | grep ^codex-worker-

完了した worker を終了します：

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

マージ後に worktree をクリーンアップします：

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 {}