Codex Worktreeとは何か
OpenAIのドキュメントはその目的から始まっています。「Worktreeを使用すると、Codexは同じプロジェクト内で互いに干渉することなく、複数の独立したチャットを実行できます。」
内部的には、Codex WorktreeはGit worktreeです。「Worktreeは内部でGit worktreeを使用しているため、Gitリポジトリの一部であるプロジェクトでのみ機能します。」ドキュメントはその意味を次のように説明しています。「各Worktreeはリポジトリ内のすべてのファイルの独自のコピーを持ちますが、コミット、ブランチなどのメタデータ(.gitフォルダ)はすべて共有されます。」
ChatGPTデスクトップアプリでは、3つの用語が使用されます:
- Local:あなた自身のチェックアウト、つまり作成したリポジトリです。
- Worktree:アプリがローカルチェックアウトから作成したGit worktreeです。
- Handoff:LocalとWorktreeの間でチャットを移動させるフローです。
OpenAIは、これらをフォアグラウンドとバックグラウンドとして考えることを提案しています。「Localをフォアグラウンド、Worktreeをバックグラウンドと考えることができます。」
リポジトリとWorktreeは、プロジェクトを保持しているマシン上に留まります。「Worktreeはスマートフォンのローカルでは実行されません。」ChatGPTモバイルアプリからWorktreeチャットを開始、ガイド、承認、レビューすることは可能ですが、それは接続されたコンピュータ上のCodexを制御することで行われます。
Worktreeでチャットを開始する方法
手順は簡単です:
- 新しいチャット画面で、コンポーザーの下にあるWorktreeを選択します。オプションで、セットアップスクリプトを実行するためのローカル環境を選択します。
- コンポーザーの下で、WorktreeのベースとなるGitブランチを選択します。
- プロンプトを送信します。CodexはそのブランチからWorktreeを作成します。
- 準備ができたら、Worktreeで作業を続けるか、チャットをLocalにHandoff(引き継ぎ)します。
プロジェクトがGitリポジトリ内にある必要があります。
新しいWorktreeに含まれるもの
Worktreeは空のフォルダではありません。OpenAIのドキュメントには、Codexがそこに何を配置するかが正確に記載されています。
ブランチの最新コミット。 「開始コミットは、チャット開始時に選択されたブランチのHEADコミットです。」
未コミットの変更(それらを含むブランチを選択した場合)。 「ローカルの変更があるブランチを選択した場合、Codexは未コミットの変更もWorktreeに適用します。」
すべての追跡対象ファイル。 「ローカルのCodex管理WorktreeはGitチェックアウトから開始されるため、追跡対象ファイルはすでに存在しています。」
独自のブランチは持たない。 「Worktreeはブランチとしてチェックアウトされません。」これはdetached HEAD状態であり、ドキュメントはその理由を次のように述べています。「これにより、Codexはブランチを汚染することなく複数のWorktreeを作成できます。」
ローカルの指示(instruction)の上書き。 Codexは1つの無視されたファイルを自動的にコピーします。「Codexは無視されたAGENTS.override.mdをローカル管理Worktreeに自動的にコピーするため、.worktreeincludeにリストする必要はありません。」このファイルにCodexへの個人用の指示を保持している場合、それらはWorktreeにも存在します。
セットアップスクリプトがインストールするもの。 ローカル環境を選択した場合、そのセットアップスクリプトが実行されます。OpenAIは、なぜこれが重要なのかを説明しています。「Worktreeはローカルチャットとは異なるディレクトリで実行されるため、プロジェクトが完全にセットアップされておらず、リポジトリにチェックインされていない依存関係やファイルが不足している可能性があります。」また、「セットアップスクリプトは、新しいチャットの開始時にCodexが新しいWorktreeを作成するときに自動的に実行されます。」
新しいWorktreeから除外されるもの
Gitチェックアウトから開始することの裏返しとして、Gitが無視するものは、明示的に指定しない限り残されます。
デフォルトでは無視されるファイル。 OpenAIの例には、.envファイルやシークレットファイルが含まれます。特定のファイルを移動させるには、リポジトリのルートに.worktreeincludeファイルを追加し、コピーするパスまたはパターンをリストします。ドキュメントは制限について正確に述べています。「Codexは.worktreeincludeに一致する無視されたファイルのみをコピーします。Gitが追跡していない他のローカルファイルはコピーしません。」
インクルードリスト内の追跡対象ファイル。 「追跡対象ファイルをリストしないでください。」それらはすでに存在しています。
シンボリックリンクと既存のファイル。 「Codexはソースのシンボリックリンクをスキップし、新しいチェックアウトにすでに存在するファイルを上書きしません。」
その他の種類のWorktree。 このインクルード動作には適用範囲があります。「この動作は、ローカルのChatGPTデスクトップアプリ管理のWorktreeに適用され、リモートWorktreeやコマンドラインから自分で作成したGit worktreeには適用されません。」
インストールされた依存関係。 セットアップスクリプトがインストールしない限り、新しいWorktreeにはnode_modulesやビルド出力がない場合があります。そのためにローカル環境のセットアップスクリプトが存在します。
LocalとWorktree間でのチャットの移動
Handoffは、チャットとそのコードを双方向に移動させます。OpenAIのドキュメントには次のようにあります。「Localへの、またはLocalからのHandoffは、チャットとコードを移動させるため、もう一方のチェックアウトで作業を継続できます。」
2つの詳細がHandoffを予測可能なものにします:
- チャットはWorktreeを保持する。 「各チャットは、時間の経過とともに同じ関連付けられたWorktreeを保持します。後でチャットをWorktreeに戻すと、Codexは同じバックグラウンド環境に戻すため、中断したところから再開できます。」
- 無視されたファイルは移動しない。 「HandoffはGit操作を使用するため、
.gitignoreファイルの一部であるファイルは、Codexが.worktreeincludeを使用してローカル管理Worktreeにコピーしない限り、チャットと一緒に移動しません。」
Handoffの詳細については、コンピュータとリモートホスト間での移動内容を含め、ガイド「Codex Handoffでチャットと共に移動するもの」で詳しく説明しています。
人々が陥りやすいブランチのルール
Gitには、Codexが回避できないルールがあります。ドキュメントには太字でこう書かれています。「Gitでは、ブランチを一度に1か所でしかチェックアウトできません。」
これは、Worktreeをブランチに変換するときに表面化します。Worktreeで「ここでブランチを作成」を選択し、その後ローカルチェックアウトでそのブランチをチェックアウトしようとすると、GitはそのブランチがすでにWorktreeで使用されているというエラーを出して拒否します。
OpenAIのアドバイス:「ブランチをローカルでチェックアウトする予定がある場合は、同じブランチを両方の場所で同時にチェックアウトしたままにしようとするのではなく、Handoffを使用してチャットをLocalに移動してください。」
CodexがWorktreeを削除するタイミング
Worktreeはスペースを消費します。「Worktreeは多くのディスク容量を占有する可能性があります。それぞれが独自のリポジトリファイル、依存関係、ビルドキャッシュなどのセットを持っています。」そのため、デスクトップアプリは保持する数を制限しています。
デフォルトの制限。 「デフォルトでは、Codexは最新の15個のCodex管理Worktreeを保持します。ディスク使用量を自分で管理したい場合は、設定でこの制限を変更したり、自動削除をオフにしたりできます。」
削除が発生するタイミング。 ドキュメントには2つのトリガーがリストされています:
- 関連するチャットをアーカイブしたとき。
- 設定された制限内に収めるために、Codexが古いWorktreeを削除する必要があるとき。
最初のケースは見落とされがちです。チャットのアーカイブはサイドバーの整理のように聞こえますが、Codex管理Worktreeを持つチャットの場合、Worktreeも削除されます。Codexでのアーカイブには他にも影響があります。これについては、ガイド「Codexエージェントコマンドセンターと、アーカイブおよび削除の機能」で説明しています。
保護されるもの。 固定(ピン留め)されたチャットに関連付けられている場合、またはチャットがまだ進行中の場合、Codex管理Worktreeは自動的に削除されません。
古い永続的なWorktree。 「以前のバージョンで作成された永続的なWorktreeは、引き続き利用可能であり、自動クリーンアップから保護されます。プロジェクトメニューから永続的なWorktreeを作成することはできなくなりました。」
削除されたWorktreeを復元する方法
Worktreeを削除してもチャットは削除されません。OpenAIのFAQには次のようにあります。「基盤となるWorktreeディレクトリが削除されても、チャットは履歴に残ります。」
そして、作業内容は事前に保存されます。「Codex管理のWorktreeを削除する前に、Codexはその上の作業のスナップショットを保存します。Worktreeが削除された後にチャットを開くと、復元するオプションが表示されます。」
したがって、回復パスは単純です。チャットを開き、復元オプションを選択するだけです。
ドキュメントには、スナップショットがどのくらいの期間保持されるか、またスナップショットに.worktreeincludeを通じてコピーされた無視されたファイルが含まれるかどうかは記載されていません。Worktreeに、ローカルのシークレットや生成されたファイルなど、再現できないものが含まれている場合は、スナップショットに頼るのではなく、独自のコピーを保持してください。
Worktreeの保存場所
「Codexは$CODEX_HOME/worktreesにWorktreeを作成します。」この場所は変更可能です。OpenAIのFAQによると、Settings(設定)を開き、Worktreesを選択して、Worktree rootを変更します。
これは、ホームドライブの容量が小さい場合や、より高速なディスクにWorktreeを置きたい場合に便利です。また、手動でディスク容量をクリーンアップする際にも知っておく価値があります。固定されたチャットや進行中のチャットの保護、およびスナップショットの手順は、Codex自身のクリーンアップのために文書化されており、ユーザーが自分で削除するフォルダには適用されません。
スケジュールされたタスク用のWorktree
Worktreeは、自分で開始するチャットのためだけのものではありません。「Gitリポジトリの場合、スケジュールされたタスクは専用のバックグラウンドWorktreeで実行できるため、進行中の作業と競合しません。」
Git以外のプロジェクトでは動作が異なります。「バージョン管理されていないプロジェクトでは、スケジュールされたタスクはプロジェクトディレクトリで直接実行されます。」
Worktreeが保持しないもの
Worktreeはファイルを保持します。それに付随するチャットは会話を保持します。どちらも保持するように設計されていないのは、あるチャットから次のチャットへと引き継がれる「推論(reasoning)」です。なぜこのアプローチが選ばれたのか、どの代替案が失敗したのか、そしてコードが何を待っているのかといった情報です。
Worktreeは設計上、使い捨て可能です。削除されたとき、スナップショットは作業内容を保持します。しかし、その過程で行われた決定はチャットの会話の中にあり、チャットが数十個になると見失いやすくなります。
人々が最初に試すこと
整理のために古いチャットをアーカイブする。 Codex管理Worktreeを持つチャットの場合、アーカイブするとWorktreeが削除されます。
新しいWorktreeに.envファイルがあることを期待する。 無視されたファイルは、.worktreeincludeに一致しない限りコピーされません。
Worktreeのブランチをローカルでチェックアウトする。 Gitはブランチを一度に1か所でのみ許可します。代わりにHandoffを使用してください。
Worktreeフォルダを手動で削除する。 スナップショットの手順はCodex自身のクリーンアップ用であり、手動で削除したフォルダには適用されません。
Worktreeと共にチャットも消えたと思い込む。 チャットは履歴に残り、チャットからWorktreeを復元できます。
解決策:作業を失わずにWorktreeを活用する
ステップ 1: 新しいWorktreeに必要なものを設定する
依存関係のためのローカル環境セットアップスクリプトと、Worktreeが必要とする無視されたファイルのための.worktreeincludeファイルを追加します。
ステップ 2: 後で見返すチャットを保護する
Worktreeを保持したいチャットをピン留めするか、設定で制限数を増やします。
ステップ 3: やり直す代わりに復元する
Worktreeが削除された場合は、最初からやり直す前にチャットを開いて復元オプションを使用します。
ステップ 4: 推論を書き留める
アプローチや除外した案など、Worktreeの変更の背後にある決定事項をチャットの外に保持します。
MemoryLakeでのセットアップ
Worktreeは並行作業に適した場所であり、Codexはクリーンアップ前に注意深く保存してくれます。その作業の背後にある決定事項こそが、新しいWorktreeやLocalでの次のチャットが、再質問することなく引き継ぐべきものです。
MemoryLakeは、決定事項、制約、規約などのプロジェクトのコンテキスト(context)のための記憶(memory)レイヤーです。これらを1か所にまとめて維持し、ChatGPT、Claude Code、Codexなどの接続したアシスタントが利用できるようにします。
エントリはあなた自身の言葉で書きます。Worktree、そのスナップショット、Codexチャット、.worktreeincludeやAGENTS.override.mdファイル、Codexの記憶、あるいはベンダーのストアから何かが読み取られたり、書き込まれたり、削除されたりすることはありません。Worktree、Handoff、およびクリーンアップは、OpenAIが説明している通りに機能します。
ステップ 1: APIキーを作成する
サインインし、ダッシュボードからキーを生成します。他の認証情報と同様にリポジトリの外に保存し、.worktreeincludeには追加しないでください。

ステップ 2: 最初の記憶をアップロードする
解決策のステップ4で書いた内容から始めましょう。各作業のアプローチ、試した代替案、それを形作った制約などです。1つのエントリにつき1つの決定事項を記述します。

ステップ 3: AIとエージェントを接続する
Codexや、使用している他のアシスタントを接続します。新しいWorktreeでの新しいチャットも、LocalにHandoffされたチャットも、同じ決定事項を参照できます。

実践で何が変わるか
第一の違いは、クリーンアップが推論(reasoning)に対するリスクではなくなることです。Worktreeがアーカイブされ削除されても、その背後にある決定事項は依然として記録されています。
第二に、並行チャットの開始が早くなります。新しいWorktreeチャットは、プロジェクトの確定した決定事項を再発見する代わりに、それらを利用することができます。
第三に、ツール間での継続性です。同じリポジトリで作業するClaude Codeや他のアシスタントも、同じエントリを使用できます。
Codex Worktreeのベストプラクティス
バックグラウンド作業にWorktreeを使用する。 アクティブにテストしている作業にはLocalを保持します。
セットアップスクリプトを追加する。 何かがインストールしない限り、新しいWorktreeには依存関係がない場合があります。
無視されたファイルを.worktreeincludeにリストする。 一致する無視されたファイルのみがコピーされます。
再訪するものをピン留めする。 ピン留めされたチャットはWorktreeを保持します。
意図的にアーカイブする。 アーカイブすると、チャットのCodex管理Worktreeが削除されます。
やり直す前に復元する。 Codexは管理Worktreeを削除する前にスナップショットを保存します。
「なぜ(why)」は別の場所に保管する。 Worktreeはファイルを保持しますが、理由は保持しません。
結論
Codex Worktreeは、チャットがローカルチェックアウトに触れることなくバックグラウンドで作業できるように、ChatGPTデスクトップアプリが作成するGit worktreeです。選択したブランチのHEADコミットから開始され、そのブランチに未コミットの変更があればそれを含み、すべての追跡対象ファイルを保持し、.worktreeincludeにリストした無視されたファイルとAGENTS.override.mdのみをコピーします。
Codexはデフォルトで最新の15個の管理Worktreeを保持し、チャットをアーカイブするとそのWorktreeを削除します。ピン留めされたチャットや進行中のチャットは保護され、管理Worktreeを削除する前に、Codexはチャットから復元可能なスナップショットを保存します。作業の背後にある推論は、次のチャットが読み取れる場所に保管しておきましょう。