Codex Worktree 実践ガイド：複数の AI 開発タスクを並行してもリポジトリを汚さない

同じリポジトリで 3 つのタスクを同時に走らせているとします。fix/auth-expired-session、test/payment-webhook、docs/setup-node20。main checkout の git status には、ログイン bug の修正、テスト fixture、README の Node 20 追記が混ざっています。3 種類の変更が 1 つの checkout に入り、どれを単独でコミットできるのか、どれがほかの変更に影響するのかが見えなくなります。

これは「並行タスク」という抽象論ではありません。Git checkout が汚れたときに起きる、かなり具体的な事故です。Codex app の Worktree モードは、タスクごとにディレクトリとブランチを分けます。各作業ラインの diff をレビューでき、マージでき、必要なら戻せる状態にするためです。

Local / Worktree / Cloud：3 つのモードをどう選ぶか

Codex app には 3 つの実行モードがあります。Local と Worktree はどちらも本機で動きます。公式ドキュメントでも “Both Local and Worktree threads will run on your computer” と明記されています。一方、Cloud はリモート環境で動きます。

モード	実行場所	変更先	向いている場面	リスクとコスト
Local	本機	main checkout	単一タスク、安定した開発	main ディレクトリを直接変更するため、未完了の作業が混ざりやすい
Worktree	本機	独立ディレクトリ + branch	複数タスクの並行実行、新しい案の試行	setup scripts と .worktreeinclude の設定が必要
Cloud	リモート	Cloud 環境	CI/CD、リモートビルド	別記事で扱う

Worktree モードは、独立したタスクを並行で進めるときや、新しい案を試すときに向いています。各 thread が自分のディレクトリと branch を持つため、main checkout は影響を受けません。Local モードはシンプルですが、複数タスクが混ざるとコミットを分けるのが難しくなります。Cloud モードは本機から完全に離れ、CI/CD やリモートビルドに向いています。

判断はシンプルです。単一タスクなら Local、複数タスクの並行実行や試行錯誤なら Worktree、リモート作業なら Cloud を選びます。

Codex app の Worktree モードを詳しく見る

Worktree の作成と Handoff

Codex app で Worktree thread を作る流れは次のとおりです。

1. 新しい thread を作成する
2. Worktree モードを選ぶ（UI の入口名は 2026-06-18 時点から変わる可能性があります）
3. 開始 branch を選ぶか、デフォルトの detached HEAD で作業する
4. 最初の prompt を送る
5. Codex が独立ディレクトリで作業を始める

デフォルトでは、Codex は detached HEAD で作業します。そのまま worktree 内で作業を続け、必要になったタイミングで branch を作れます。Handoff は、Local と Worktree の間で thread とコードを移動する機能です。

Handoff の場面：

Worktree から Local へ：タスク完了後、まだ detached HEAD なら先に worktree 内で branch を作ります。その後 Handoff で Local に戻し、最後に merge するか PR を作ります。

Local から Worktree へ：未完了の作業を隔離環境に移して、main checkout を汚さず続けたいときに使います。

Handoff は単なるディレクトリ切り替えではありません。現在の thread context、prompt 履歴、未完了の変更も一緒に移動します。

Codex-managed worktree の特徴

Codex-managed worktrees には、覚えておきたい挙動がいくつかあります。

デフォルトの場所：$CODEX_HOME/worktrees

デフォルトの保持数：15 個（2026-06-18 時点の公式ドキュメント）。超えたものは自動クリーンアップされることがあります。

Permanent worktree：手動で作成した worktree は自動削除されません。

Branch 制限：Git は同じ branch が複数 worktree で同時に checkout されることを許しません。切り替えようとするとエラーになります。

ルール継承：AGENTS.override.md は worktree に自動コピーされ、プロジェクトルールをそろえられます。

つまり、worktree の数には上限があり、古いものは整理される可能性があります。同じ branch は並行利用できません。プロジェクトルールは自動で引き継がれます。

.worktreeinclude で ignored files の問題を避ける

Worktree はデフォルトで Git tracked files だけを引き継ぎます。.gitignore に入っているファイルは、Handoff で自動的に移動しません。よく欠けるのは .env、.env.local、依存キャッシュ、ローカル設定ファイルです。

対策は、プロジェクトルートに .worktreeinclude を作り、コピーしたい ignored files を明示することです。例：

.env
.env.local
node_modules/.cache

こうしておくと、Handoff 時に .gitignore 内のファイルも worktree へコピーできます。

Setup scripts：worktree 内でプロジェクトを動かせるようにする

Worktree は別ディレクトリにあるため、依存関係や check in されていないファイルが欠けることがあります。Setup scripts は新しい worktree や新しい thread の開始時に自動実行され、環境を使える状態にします。

設定手順：

1. Codex app の Local environments で setup steps を設定する
2. 設定ファイル用に .codex ディレクトリを作る
3. プラットフォーム別のスクリプトを書く

Node.js プロジェクトの例：

# .codex/setup.sh
npm install
npm run build

Python プロジェクトの例：

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Setup scripts は新しい worktree が作られるたびに実行されます。手作業で依存関係を入れ直す負担を減らせます。ただし、設定 UI やファイル形式は 2026-06-18 以降に変わる可能性があります。現在の公式ドキュメントと照らし合わせてください。

Codex app を使わなくても Plain Git worktree で隔離できる

CLI やターミナル中心の運用なら、Git worktree コマンドで直接隔離ディレクトリを作り、そのディレクトリで Codex を起動できます。Codex app の管理機能は不要ですが、管理はすべて自分で行います。

Git Worktree のよく使うコマンド：

# 公式ユースケースに近い形で新しい worktree と branch を作る
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# 既存 branch から新しい worktree を作る
git worktree add ../task-b existing-branch

# すべての worktrees を一覧する
git worktree list

# worktree を削除する
git worktree remove ../task-a

# 古い worktree メタデータを整理する
git worktree prune

Codex-managed と Plain Git の比較：

特性	Codex-managed	Plain Git
作成方法	App UI で自動	git worktree add
場所の管理	$CODEX_HOME/worktrees	手動指定
クリーンアップ方針	デフォルトで 15 個を自動保持	手動 prune
Handoff	App 内で切り替え	手動で cd する
Setup scripts	自動実行	手動設定

Plain Git worktree は CLI 派の開発者に合います。ただし、依存関係のインストール、環境設定、クリーンアップを自分で処理する必要があります。Codex-managed worktree は、そのあたりを自動化してくれます。

Automations のバックグラウンドタスクに worktree は必要か

Git リポジトリ内の automation は、local project でも dedicated background worktree でも実行できます。どちらを選ぶかは、タスクの種類とリスク管理で決まります。

判断ロジック：

Local モードは単発タスクや一時的なテストに向いています。main checkout を直接変更するため、未完了の作業が混ざる可能性があります。あなたが編集中のファイルを、バックグラウンド automation が同時に変更することもあります。

Worktree モードは、繰り返しタスクや定期タスクに向いています。automation changes と unfinished local work を分離できます。automation は独立ディレクトリで動くため、main checkout に影響しません。

リスクの注意点：

Automations は default sandbox settings を使います（2026-06-18 以降に変わる可能性があります）。

Full access 権限ではバックグラウンド automation のリスクが高くなるため、worktree を使うべきです。

繰り返し実行するバックグラウンドタスクを Local で直接走らせないでください。

原則として、単発の一時タスクは Local でもよいですが、繰り返しタスクと full access のバックグラウンド作業は Worktree に寄せます。

並行に向くタスク、直列にすべきタスク

公式ユースケースでは、異なる探索を別々の worktree に分けることが推奨されています。実際には、ファイル衝突と依存関係を見て判断する必要があります。

タスク並行戦略の判断表：

タスク種別	並行可否	理由	推奨
独立ファイルの修正（別モジュール）	並行しやすい	ファイル衝突リスクが低い	複数 worktree を同時に開く
新機能開発（独立コンポーネント）	並行しやすい	モジュール境界が明確	コンポーネントごとに 1 worktree
同じファイルの複数箇所修正	直列にする	マージ時に衝突する	優先順位を決めて 1 つずつ完了
依存関係のあるタスク	直列にする	前のタスクが次の入力になる	前段タスクを完了してから開始
ドキュメント更新	並行しやすい	多くの場合、独立ファイルを触る	ほかのタスクと並行可能

並行の原則：

互いに依存しない小さなタスク 2 つから始めます。最初から 5〜6 個は開きません。

タスク数は 3〜4 個程度に抑えます。レビューコストを下げるためです。

各タスクに明確な検証基準を置きます。

過度な並行はすすめません。タスクが増えるほど、レビューコストと merge conflict のリスクも上がります。

タスクカードテンプレート：各 worktree が何をするかを書いておく

各 worktree を始める前に、タスク内容を明確に書いておくと、検証と追跡が楽になります。

タスクカード例：

Goal: "auth モジュールの session expired bug を修正する"
Context:
  - "ユーザーの session は 30 分で期限切れになるが、フロントエンドに通知が出ない"
  - "関連ファイル：src/auth/session.js、src/components/AuthProvider.jsx"
Constraints:
  - "データベース schema は変更しない"
  - "新しい依存関係を追加しない"
Done when:
  - "session 期限切れ時にフロントエンドが通知を表示する"
  - "npm test が通る"
  - "ログインフローを手動テストする"

Branch/Worktree: "fix/auth-expired-session"
検証コマンド: "npm test && npm run lint"

記入ポイント：

Goal：目的を 1 文で書く

Context：ファイル、モジュール、背景を渡す

Constraints：境界を明確にする（何を変えないか）

Done when：検証可能な完了条件を書く

Branch/Worktree：task-type/module-description のようにわかりやすく命名する

検証コマンド：実行できる具体的なコマンドを書く

これで各 worktree の境界がはっきりします。レビュー時は Done when に照らして確認できます。

マージキュー：1 つずつ review、test、merge する

並行タスクが完了しても、結果をまとめて main に流し込まないでください。リスク順に並べ、1 つずつ review、test、merge します。

マージキューの手順：

1. worktree をリスク順に並べる（最小リスクから）
2. 最初の worktree で行うこと：
   • 検証コマンドを実行する（テスト、lint）
   • diff を確認する（変更範囲が想定どおりか）
   • まだ detached HEAD なら branch を作る
   • PR review の基準に沿って diff をレビューする
3. Local にマージするか PR を作る：
   • Local マージ：Handoff で Local に戻してから merge
   • PR マージ：PR を作り、CI と review を待つ
4. 次の worktree でも同じ手順を繰り返す
5. すべて完了したら main branch にマージする

検証チェックリスト：

検証コマンドが通る（テスト、lint）

Diff チェック：変更範囲が想定どおり

Review guidelines：sensitive files や hard-coded secrets がない

CI が通る（ある場合）

手動テストフロー

リスクの注意点：

複数 worktree の結果を自動でマージできるとは約束しない

同じファイルを複数箇所で変更した場合は、手動で conflict を解決する

必ず人間の review とテストを残す

マージキューの目的は、各作業ラインの diff をレビュー可能で戻せる状態にすることです。一度にすべてコミットすることではありません。

トラブルシューティングチェックリスト

"branch already used by worktree" エラー

原因：branch がほかの worktree で使われています。

解決方法：

git worktree list で、どの branch が使われているか確認します。

別の branch を選ぶか、その branch を使っている worktree を削除します。

worktree の中でコードが動かない

原因：依存関係または設定ファイルが欠けています。

確認手順：

.env、.env.local が存在するか確認します（コピーされていない可能性があります）。

依存関係がインストール済みか確認します（node_modules、venv）。

設定ファイルがそろっているか確認します。

解決方法：

.worktreeinclude を設定して ignored files をコピーします。

Setup scripts を設定して依存関係を自動インストールします。

worktree のディスク使用量が膨らむ

原因：頻繁な automations によって多くの worktrees が作られています。

解決方法：

不要になった automation runs を archive します。

手動で git worktree prune を実行し、古い worktree を整理します。

Codex app の worktree 保持設定を確認します（2026-06-18 以降に変わる可能性があります）。

agent が作った worktree と UI/thread context が同期しない

原因：agent が自動で worktree を作ると、App UI を経由しない場合があります。

解決方法：

git worktree list で全 worktrees を確認します。

App 内で thread と worktree のひも付きを手動確認します。

agent に worktree を自動作成させず、App UI から手動で作成します。

トラブルシューティングの基本は、まず git worktree list で worktree 状態を見て、エラーの種類ごとに対処することです。

コスト判断：並行タスクは quota を消費しやすい

並行タスクは、turn や quota を多く消費しやすくなります。各 worktree は独立した session であり、Codex は session ごとに計上されます。

コスト判断：

並行タスク数は 3〜4 個程度に抑えます。

互いに依存しない小さなタスク 2 つから始めます（レビューコストを下げるため）。

各タスクに明確な検証基準を置き、無制限な反復を避けます。

具体的な価格、quota、plan 情報は、後続の Cost & Quota 管理記事を参照してください。ここでは未確認の数字を展開しません。

次のステップと関連読み物

上流記事：

Codex の入口選び：Local / Worktree / Cloud モードの簡単な紹介

AGENTS.md プロジェクトルール：各 worktree が同じルールをどう継承するか