Worktrees (ワークツリー)

内部で Git worktrees を使うため、Git リポジトリに含まれるプロジェクトでだけ使えます。リポジトリ、ワークツリー、実行されるコマンドは、プロジェクトがあるコンピューターまたはリモートの開発環境に置かれたままです。

チャットは既定で Codex-managed worktree (Codex が管理するワークツリー) を使います。このワークツリーは通常 1 つのチャット専用です。

• 作成場所は $CODEX_HOME/worktrees です。開始コミットは、チャット開始時に選んだブランチの HEAD コミットです。
• ローカル変更のあるブランチを選んだ場合は、コミットしていない変更もワークツリーに適用されます。
• 作成場所を変えるには、Settings > Worktrees (設定 > ワークツリー) を開き、Worktree root (ワークツリーのルート) を変更します。ワークツリーの作成は、コンピューターで設定された保存場所に従います。
• Git worktrees を内部で使うため、Git リポジトリに含まれるプロジェクトでだけ動作します。

ワークツリーでの作業を続ける場合は、チャットのヘッダーにある Create branch here (ここにブランチを作成) ボタンでワークツリーをブランチにします。その後、変更のコミット、リモートリポジトリへのブランチの push、GitHub でのプルリクエストの作成ができます。ヘッダーの Open (開く) ボタンで IDE をワークツリーに対して開くことも、統合ターミナルを使うこともできます。なお、ワークツリー上で作成したブランチは、Local のチェックアウトを含むほかのワークツリーではチェックアウトできません。

チャットを手元で扱いたい場合は、チャットのヘッダーで Hand off (引き渡し) を選び、Local (ローカル) へ移します。逆に Local で作業中に手を空けたい場合は、Hand off でチャットをワークツリーへ移すと、Codex がバックグラウンドで作業を続けます。各チャットは同じワークツリーと結び付いたままで、後でワークツリーへ戻すと同じバックグラウンド環境に戻ります。

Handoff は Git の操作を使うため、.gitignore の対象のファイルはチャットと一緒には移動しません。ただし、.worktreeinclude によって Codex がローカルの管理ワークツリーへコピーしたファイルは別です。

Git が無視しているファイルを管理ワークツリーへ持ち込みたい場合は、リポジトリのルートに .worktreeinclude ファイルを置き、コピーする無視対象のパス、または .gitignore 形式のパターンを列挙します。Codex が管理ワークツリーを作成するときに、それらがコピーされます。

• コピーされるのは .worktreeinclude に一致する無視ファイルだけで、Git が追跡していないほかのローカルファイルはコピーされません。
• 無視されている AGENTS.override.md は自動でコピーされるため、.worktreeinclude に書く必要はありません。
• コピー元のシンボリックリンクはスキップされ、新しいチェックアウトに既にあるファイルは上書きされません。
• この動作の対象は、ローカルの ChatGPT デスクトップアプリが管理するワークツリーです。リモートのワークツリーや、コマンドラインで自分で作成した Git worktree は対象外です。

Codex は既定で、直近 15 個の Codex-managed worktree を保持します。上限の変更や自動削除の無効化は設定から行えます。

• 自動で削除されるのは、関連するチャットをアーカイブしたとき、または設定した上限に収めるために古いワークツリーを消す必要があるときです。
• ピン留めしたチャットに結び付いている場合や、チャットが進行中の場合は自動では削除されません。
• 削除の前に、Codex はワークツリー上の作業のスナップショットを保存します。ワークツリーが削除された後でチャットを開くと、復元の選択肢が表示されます。
• 以前のバージョンで作成した永続的なワークツリーは引き続き使え、自動削除の対象になりません。ただし、プロジェクトメニューから永続的なワークツリーを新たに作成することはできません。

エージェント一覧では、ワークツリーの所有者情報が表示され、クリーンな管理ワークツリーを確認のうえで削除できます。

新しいチャットをワークツリーで始める流れです。

1. 新しいチャットの画面で、composer (入力欄) の下にある Worktree (ワークツリー) を選びます。必要なら local environment (ローカル環境) を選び、ワークツリー用のセットアップスクリプトを実行させます。
2. composer (入力欄) の下で、ワークツリーの基にする Git ブランチを選びます。main / master ブランチ、feature ブランチ、または unstaged のローカル変更を含む現在のブランチを選べます。
3. プロンプトを送信すると、Codex が選んだブランチを基に Git worktree を作成します。既定では detached HEAD の状態で作業します。
4. 準備ができたら、そのままワークツリー上で作業を続けるか、チャットを Local のチェックアウトへ引き渡します。Local との引き渡しでは、チャットとコードの両方が移動します。