Worktree を使うと、Codex は同じプロジェクト内で、互いに干渉することなく複数の独立したチャットを実行できます。リポジトリと Worktree はプロジェクトのあるコンピューターまたはリモート開発環境に置かれ、コマンドもそこで実行されます。ChatGPT デスクトップアプリで直接作業できるほか、ChatGPT モバイルアプリのリモートを使用して、接続先のコンピューター上の Worktree チャットを開始し、指示を出したり、承認やレビューを行ったりできます。
Git リポジトリでは、スケジュール済みタスクを専用のバックグラウンド Worktree で実行できるため、進行中の作業と競合しません。バージョン管理されていないプロジェクトでは、スケジュール済みタスクはプロジェクトディレクトリで直接実行されます。また、Worktree でチャットを手動で開始し、引き継ぎを使ってローカルと Worktree の間でチャットを移動することもできます。
Worktree はスマートフォン上のローカル環境では実行されません。リモートを使用すると、接続先のコンピューター、またはそのコンピューターが利用するリモート開発環境で動作する Codex を、モバイルアプリから操作できます。リポジトリと Worktree は、そのコンピューターまたはリモート開発環境に置かれたままです。以下のデスクトップ向けの手順は、接続先のコンピューターで行ってください。
Worktree とは
Worktree は内部で Git Worktree を使用するため、Git リポジトリに含まれるプロジェクトでのみ動作します。Worktree を使うと、リポジトリの 2 つ目のコピーである「チェックアウト」を作成できます。各 Worktree にはリポジトリ内のすべてのファイルのコピーがありますが、コミットやブランチなどのメタデータ（.git フォルダー）は、すべての Worktree で共有されます。これにより、複数のブランチをチェックアウトし、並行して作業できます。
用語
- ローカルチェックアウト：自分で作成したリポジトリです。ChatGPT デスクトップアプリでは、単に ローカル と呼ばれることもあります。
- Worktree：ChatGPT デスクトップアプリでローカルチェックアウトから作成された Git Worktree です。
- 引き継ぎ：ローカルと Worktree の間でチャットを移動する仕組みです。両者の間で作業内容を安全に移動するために必要な Git 操作は、Codex が処理します。
Worktree を使用する理由
- 現在のローカル環境の設定に影響を与えず、Codex と並行して作業できます。
- フォアグラウンドの作業に集中しながら、バックグラウンドの作業をキューに追加できます。
- 内容の確認やテスト、より直接的な共同作業を始める準備が整ったら、チャットを後からローカルに移動できます。
はじめに
Worktree を使用するには Git リポジトリが必要です。選択したプロジェクトが Git リポジトリ内にあることを確認してください。
-
「Worktree」の選択
新しいチャット画面で、コンポーザーの下にある Worktree を選択します。 必要に応じて、Worktree 用のセットアップスクリプトを実行するローカル環境を選択します。
-
開始ブランチの選択
コンポーザーの下で、Worktree のベースとなる Git ブランチを選択します。
main/masterブランチ、機能ブランチ、またはステージングされていないローカルの変更を含む現在のブランチを選択できます。 -
プロンプトの送信
プロンプトを送信すると、Codex は選択したブランチを基に Git Worktree を作成します。デフォルトでは、Codex は「detached HEAD」の状態で作業します。
-
作業を続ける場所の選択
準備が整ったら、Worktree で直接作業を続けるか、チャットをローカルチェックアウトに引き継ぐことができます。ローカルへの引き継ぎでもローカルからの引き継ぎでも、チャット と コードの両方が移動するため、もう一方のチェックアウトで作業を続けられます。
ローカルと Worktree の間での作業
Worktree の見た目や操作感は、ローカルチェックアウトとほぼ同じです。異なるのは、作業の流れにおける位置付けです。ローカルをフォアグラウンド、Worktree をバックグラウンドと捉えることができます。引き継ぎを使うと、両者の間でチャットを移動できます。
引き継ぎでは、2 つのチェックアウト間で作業内容を安全に移動するために必要な Git 操作が内部で処理されます。これは、 Git ではブランチを同時に 1 か所でしかチェックアウトできないため重要です。Worktree でブランチをチェックアウトすると、ローカルチェックアウトで同じブランチを同時にチェックアウトすることは できません 。逆も同様です。
実際には、主に次の 2 つの方法があります。
- Worktree だけで作業する。たとえば、ローカル環境のセットアップスクリプトを使って依存関係やツールをインストールしており、Worktree 上で変更を直接検証できる場合に適しています。
- チャットをローカルに引き継ぐ。普段使っている IDE で変更を確認したい場合や、アプリのインスタンスを 1 つしか実行できない場合など、チャットをフォアグラウンドに移したいときに使用します。
選択肢 1：Worktree での作業
変更内容を Worktree に保持し、その Worktree だけで作業を続ける場合は、チャットヘッダーの ここにブランチを作成 ボタンを使って Worktree をブランチ化します。
ここから変更をコミットし、ブランチをリモートリポジトリにプッシュして、GitHub で Pull Request を作成できます。
ヘッダーの「開く」ボタンを使って Worktree を IDE で開いたり、統合ターミナルを使用したりするなど、Worktree ディレクトリで必要な作業を行えます。
Worktree でブランチを作成すると、ローカルチェックアウトを含む他の Worktree では、そのブランチをチェックアウトできない点に注意してください。
選択肢 2：チャットのローカルへの引き継ぎ
チャットをフォアグラウンドに移すには、チャットヘッダーで 引き継ぐ を選択し、 ローカルに移動します。
普段使っている IDE のウィンドウで変更内容を確認したい場合や、既存の開発サーバーを実行したい場合、または日常的に使っている環境で作業結果を検証したい場合に適した方法です。
Codex は、Worktree とローカルチェックアウトの間でチャットを安全に移動するために必要な Git 操作を処理します。
各チャットは、継続して同じ Worktree に関連付けられます。後からチャットを Worktree に引き継ぎ直すと、Codex が元のバックグラウンド環境に戻すため、中断したところから作業を再開できます。
逆方向にも移動できます。すでにローカルで作業していてフォアグラウンドを空けたい場合は、 引き継ぐ を使ってチャットを Worktree に移動します。Codex にバックグラウンドで作業を続けてもらいながら、ローカルで別の作業に戻りたい場合に便利です。
引き継ぎでは Git 操作を使用するため、.gitignore ファイルに記載されたファイルは、Codex が .worktreeinclude を使ってローカルの管理対象 Worktree にコピーしない限り、チャットと一緒には移動しません。
上級者向けの詳細
Codex 管理の Worktree と永続 Worktree
デフォルトでは、チャットは Codex 管理の Worktree を使用します。これは軽量で、使い捨てることを前提としています。Codex 管理の Worktree は通常 1 つのチャット専用であり、後からそのチャットを引き継ぎ直すと、Codex は同じ Worktree に戻します。
長期間使える環境が必要な場合は、サイドバーのプロジェクトにある 3 点メニューから永続 Worktree を作成します。これにより、新しい永続 Worktree が独立したプロジェクトとして作成されます。永続 Worktree は自動的に削除されず、同じ Worktree から複数のチャットを開始できます。
Codex による Worktree の管理
Codex は $CODEX_HOME/worktrees に Worktree を作成します。開始時点のコミットは、チャットの開始時に選択したブランチの HEAD コミットです。ローカルの変更があるブランチを選択した場合、Codex は未コミットの変更も Worktree に適用します。Worktree はブランチとしてチェックアウトされず、detached HEAD 状態になります。これにより、Codex はブランチを不要に増やすことなく複数の Worktree を作成できます。
無視対象のローカルファイルを管理対象 Worktree にコピー
ローカルにある Codex 管理の Worktree は Git のチェックアウトから作成されるため、追跡対象のファイルはすでに存在します。新しい Worktree に必要なローカルのセットアップファイルがリポジトリで無視されている場合は、リポジトリのルートに .worktreeinclude ファイルを追加してください。そこに、Codex が管理対象 Worktree を作成するときにコピーする無視対象のパス、または .gitignore 形式のパターンを記載します。
.env、.env.local、config/secrets.json など、Git が意図的に無視するファイルに使用します。Codex がコピーするのは .worktreeinclude に一致する無視対象のファイルだけであり、Git が追跡していない他のローカルファイルはコピーしません。追跡対象のファイルは記載しないでください。
Codex は無視対象の AGENTS.override.md をローカルの管理対象 Worktree に自動的にコピーするため、.worktreeinclude に記載する必要はありません。
# .worktreeinclude
.env
.env.local
config/secrets.jsonCodex はコピー元のシンボリックリンクをスキップし、新しいチェックアウトにすでに存在するファイルは上書きしません。この動作は、ChatGPT デスクトップアプリが管理するローカルの Worktree にのみ適用されます。リモートの Worktree や、コマンドラインから自分で作成した Git Worktree には適用されません。
ブランチの制限
Codex が Worktree で作業を完了し、その Worktree に feature/a ブランチを作成するため、 ここにブランチを作成を選択したとします。そのブランチをローカルチェックアウトで試そうとしてチェックアウトすると、次のエラーが発生します。
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'この問題を解決するには、Worktree で feature/a の代わりに別のブランチをチェックアウトする必要があります。
ブランチをローカルでチェックアウトする予定がある場合は、同じブランチを両方の場所で同時にチェックアウトし続けようとせず、引き継ぎを使ってチャットをローカルに移動してください。
この制限がある理由
Git では、同じブランチを複数の Worktree で同時にチェックアウトできません。ブランチは、作業ツリーの「現在チェックアウトされている状態」を意味する、変更可能な単一の参照（refs/heads/<name>）を表すためです。
ブランチをチェックアウトすると、Git はその HEAD を当該 Worktree に属するものとして扱い、コミット、リセット、リベース、マージなどの操作によって、その参照が明確な順序に従って逐次更新されることを前提とします。複数の Worktree で同じブランチを同時にチェックアウトできるようにすると、どの Worktree の操作によってブランチの参照が更新されるのかが不明確になり、競合状態が発生します。その結果、コミットの消失、インデックスの不整合、競合解決の不明確化を招くおそれがあります。
Git は、ブランチをチェックアウトできる Worktree を 1 つに限定することで、各ブランチに対して正本となる作業コピーが 1 つだけ存在することを保証します。同時に、他の Worktree からも、detached HEAD や別のブランチを通じて同じコミットを安全に参照できます。
Worktree のクリーンアップ
Worktree は大量のディスク容量を消費することがあります。それぞれがリポジトリのファイル、依存関係、ビルドキャッシュなどを個別に保持するためです。そのため、ChatGPT デスクトップアプリでは、Worktree の数を適切な範囲に抑えるようにしています。
デフォルトでは、Codex は自身が管理する Worktree のうち、直近の 15 個を保持します。ディスク使用量を自分で管理したい場合は、設定でこの上限を変更するか、自動削除を無効にできます。
Codex は、引き続き必要な Worktree を削除しないようにします。以下のいずれかに該当する場合、Codex が管理する Worktree は自動的には削除されません。
- ピン留め済みのチャットが関連付けられている
- チャットがまだ進行中である
- 永続的な Worktree である
Codex が管理する Worktree は、以下の場合に自動的に削除されます。
- 関連付けられたチャットをアーカイブする
- 設定した上限内に収めるため、Codex が古い Worktree を削除する必要がある
Codex は、自身が管理する Worktree を削除する前に、その Worktree での作業のスナップショットを保存します。Worktree の削除後にチャットを開くと、その Worktree を復元するオプションが表示されます。
よくある質問
Worktree の作成場所を指定できますか？
はい。Codex はデフォルトで、$CODEX_HOME/worktrees 配下に管理対象の Worktree を作成します。
別の場所を指定するには、 設定 > Worktree を開き、
Worktree のルート を変更します。
チャットをローカルと Worktree の間で移動できますか？
はい。チャットのヘッダーにある 引き継ぐ を使うと、 ローカルのチェックアウトと Worktree の間でチャットを移動できます。 環境間でチャットを安全に移動するために必要な Git 操作は、Codex が処理します。 後でチャットを Worktree に引き継ぎ直すと、Codex は元から関連付けられていた Worktree にそのチャットを戻します。
Worktree が削除された場合、チャットはどうなりますか？
対応する Worktree ディレクトリが削除されても、チャットは履歴に残ることがあります。Codex が管理する Worktree では、Codex は削除前にスナップショットを保存し、関連付けられたチャットを再度開くと、その Worktree を復元するオプションを表示します。永続的な Worktree は、関連付けられたチャットをアーカイブしても自動的には削除されません。