Worktree を使うと、Codex は同じプロジェクト内で複数のチャットを並行して進められます。各チャットの作業が互いに干渉することはありません。リポジトリと Worktree はプロジェクトがあるコンピューターまたはリモート開発環境に置かれ、コマンドもそこで実行されます。ChatGPT デスクトップアプリで直接作業することも、ChatGPT モバイルアプリの Codex から、接続先のコンピューターで Worktree のチャットを開始し、作業を指示、承認、レビューすることもできます。
Git リポジトリでは、スケジュール済みタスクを専用の Worktree でバックグラウンド実行できるため、進行中の作業と競合しません。バージョン管理されていないプロジェクトでは、スケジュール済みタスクはプロジェクトディレクトリ内で直接実行されます。Worktree でチャットを手動で開始したり、引き継ぎ機能を使ってローカルと Worktree の間でチャットを移動したりすることもできます。
Worktree はスマートフォン上では動作しません。ChatGPT モバイルアプリから操作するのは、接続先のコンピューター、またはそのコンピューターが使用するリモート開発環境で動作する Codex です。リポジトリと Worktree もその環境にあります。以下のデスクトップ向けの手順は、接続先のコンピューターで行います。
Worktree とは
Worktree は内部で Git の Worktree を使うため、Git リポジトリ内のプロジェクトでのみ利用できます。Worktree を使うと、リポジトリのもう一つの作業用コピー（「チェックアウト」）を作成できます。各 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 はバックグラウンドで作業を進める場所と考えるとよいでしょう。引き継ぎ機能を使えば、この二つの間でチャットを移動できます。
引き継ぎ時には、二つのチェックアウトの間で作業を安全に移すために必要な Git の操作が内部で行われます。これは、Git では一つのブランチを一度に一か所でしかチェックアウトできないためです。Worktree でブランチをチェックアウトすると、同じブランチをローカルチェックアウトで同時にチェックアウトすることはできません。逆の場合も同様です。
一般的な作業の進め方は次の二つです。
- Worktree だけで作業を進めます。たとえば、ローカル環境のセットアップスクリプトで依存関係やツールをインストールしていて、Worktree 上で変更を直接検証できる場合に適しています。
- チャットをローカルに引き継ぎます。普段使っている IDE で変更を確認したい場合や、アプリを一度に一つしか起動できない場合など、チャットの作業を手元で進めたいときに使います。
方法 1：Worktree での作業
変更を Worktree に置いたまま、そこで作業を続けるには、チャットのヘッダーにあるここにブランチを作成ボタンを使って、その Worktree にブランチを作成します。
これで、変更をコミットし、ブランチをリモートリポジトリにプッシュして、GitHub で pull request を作成できます。
ヘッダーの「開く」ボタンを使って IDE で Worktree を開くことも、統合ターミナルを使うこともできます。ほかに必要な操作があれば、Worktree ディレクトリから実行できます。
Worktree に作成したブランチは、ローカルチェックアウトを含め、ほかの Worktree では同時にチェックアウトできないことに注意してください。
方法 2：チャットのローカルへの引き継ぎ
チャットの作業を手元で進めたい場合は、チャットのヘッダーで引き継ぐを選択し、チャットをローカルに移動します。
普段使っている IDE のウィンドウで変更内容を確認したい場合や、既存の開発サーバーを起動したい場合、日常的に使っている環境で作業結果を検証したい場合に適しています。
Worktree とローカルチェックアウトの間でチャットを安全に移すために必要な Git の操作は Codex が行います。
各チャットには、同じ Worktree が継続して関連付けられます。後でチャットを Worktree に引き継ぐと、Codex は元のバックグラウンド環境にチャットを戻すため、中断したところから作業を再開できます。
逆方向に引き継ぐこともできます。すでにローカルで作業していて、手元の環境を別の作業に使いたい場合は、引き継ぐを使ってチャットを Worktree に移動します。ローカルで別の作業に戻り、その間も Codex にバックグラウンドで作業を続けてほしいときに便利です。
引き継ぎには Git の操作を使うため、.gitignore ファイルで除外されるファイルはチャットと一緒には移動しません。ただし、Codex が .worktreeinclude を使ってローカルの管理対象 Worktree にコピーするファイルは例外です。
詳細仕様
Codex 管理の Worktree
デフォルトでは、チャットは Codex が管理する Worktree を使用します。手軽に使え、不要になったら破棄できる設計です。通常、Codex 管理の Worktree は一つのチャット専用です。後でそのチャットを Worktree に引き継ぐと、Codex は同じ Worktree にチャットを戻します。
Codex による Worktree の管理方法
Codex は $CODEX_HOME/worktrees に Worktree を作成します。起点となるのは、チャットを開始するときに選択したブランチの HEAD コミットです。ローカルの変更があるブランチを選んだ場合、Codex は未コミットの変更も Worktree に適用します。Worktree ではブランチをチェックアウトせず、detached HEAD の状態で作業します。これにより、不要なブランチを増やさずに複数の Worktree を作成できます。
管理対象 Worktree への除外ファイルのコピー
Codex がローカルで管理する Worktree は Git のチェックアウトから作成されるため、追跡対象のファイルは最初から含まれています。新しい Worktree のセットアップに必要なローカルファイルがリポジトリで除外されている場合は、リポジトリのルートに .worktreeinclude ファイルを追加します。そこに、Codex が管理対象 Worktree を作成するときにコピーするファイルのパスを列挙するか、.gitignore 形式のパターンを指定します。
この仕組みは、.env、.env.local、config/secrets.json など、意図的に Git の管理から除外しているファイルに使います。Codex がコピーするのは、除外ファイルのうち .worktreeinclude に一致するものだけです。それ以外の未追跡のローカルファイルはコピーしません。追跡対象のファイルは記載しないでください。
除外対象の AGENTS.override.md は、Codex がローカルの管理対象 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 が管理するものとして扱います。git commit、git reset、git rebase、git merge などの操作では、定まった順序で一つずつ参照を更新することを前提としています。複数の Worktree が同じブランチを同時にチェックアウトできると、どの Worktree の操作がブランチの参照を更新するのかが曖昧になり、競合状態が生じます。その結果、コミットが失われたり、インデックスに不整合が生じたり、コンフリクトをどう解消すべきか判断できなくなったりする可能性があります。
ブランチのチェックアウト先を一つの Worktree に限定することで、Git は各ブランチの基準となる作業用コピーを一つに保ちます。一方、ほかの Worktree からは、detached HEAD の状態や別のブランチで、同じコミットを安全に参照できます。
Worktree のクリーンアップ
各 Worktree はそれぞれリポジトリのファイル、依存関係、ビルドキャッシュなどを持つため、多くのディスク容量を使用することがあります。そのため、ChatGPT デスクトップアプリは Worktree の数を一定の範囲に保つようにしています。
デフォルトでは、Codex は直近 15 個の Codex 管理の Worktree を保持します。ディスク使用量を自分で管理したい場合は、設定で上限を変更したり、自動削除を無効にしたりできます。
Codex は、引き続き必要な Worktree をできるだけ削除しないようにしています。次のいずれかに該当する Codex 管理の Worktree は自動削除されません。
- ピン留めしたチャットが関連付けられている場合
- チャットが進行中の場合
以前のバージョンで作成した永続 Worktree は引き続き利用でき、自動クリーンアップの対象外です。現在は、プロジェクトメニューから永続 Worktree を新規作成することはできません。
Codex 管理の Worktree は、次の場合に自動で削除されます。
- 関連するチャットをアーカイブした場合
- 設定した上限を守るために Codex が古い Worktree を削除する必要がある場合
Codex は、管理対象 Worktree を削除する前に、そこでの作業のスナップショットを保存します。Worktree が削除された後にチャットを開くと、Worktree を復元するオプションが表示されます。
よくある質問
Worktree の作成先は変更できますか？
はい。デフォルトでは、Codex は $CODEX_HOME/worktrees の下に管理対象 Worktree を作成します。別の場所を指定するには、設定 > Worktree を開き、Worktree のルートを変更します。
ローカルと Worktree の間でチャットを移動できますか？
はい。チャットのヘッダーにある引き継ぐを使って、ローカルチェックアウトと Worktree の間でチャットを移動できます。環境間でチャットを安全に移動するために必要な Git の操作は Codex が行います。後でチャットを Worktree に引き継ぐと、Codex はそのチャットを元の Worktree に戻します。
Worktree が削除されるとチャットはどうなりますか？
対応する Worktree ディレクトリが削除されても、チャットが履歴に残ることがあります。Codex 管理の Worktree の場合、Codex は削除前にスナップショットを保存します。関連するチャットを再度開くと、Worktree を復元するオプションが表示されます。