Codex worktree：2つ目のタスク用の別の作業コピー

たとえば、Codex CLIであるモジュールをリファクタリングしているときに、別のモジュールのテストを書くという2つ目のタスクが発生したとします。同じフォルダーで2つ目のセッションを開くのは危険です。1つ目と2つ目のタスクの変更を混同しやすいためです。--worktreeフラグを使うと、2つ目のタスク用に同じプロジェクトの別フォルダーが作成され、1つ目の作業には手を加えずに済みます。

エージェントとの並行作業に役立つ実践的な資料：Ailootのドキュメント。

--worktreeで作成されるものと、コピーに含まれるファイル#

Gitの用語では、worktreeは同じリポジトリに紐付いた追加の作業フォルダーです。コミット履歴を共有しつつ、ディスク上には独自のファイル一式を持ちます。Codex CLI 0.155.1では、--worktreeフラグはこのGitの仕組みを使って別フォルダーで新しいエージェントセッションを開始し、1つ目のタスクがすでに実行されているフォルダーには手を加えません。

新しい作業コピーには、起動時に元のプロジェクトのHEADが指しているコミットのファイルが含まれます。つまり、エディターで最後にファイルを保存した時点ではなく、最新のコミットの内容です。このコマンドは未コミットの変更や新しいファイルを移しません。エディターで保存することとGitでコミットすることは同じではありません。2つ目のタスクを起動した時点で1つ目のフォルダーに未コミットの変更が残っている場合、その変更はそのフォルダーだけに残ります。

これはリポジトリ全体のバックアップでも、コンピューター全体の分離でもありません。同じプロジェクトの2つ目の作業フォルダーであり、同じブランチとコミット履歴にアクセスできます。別のツールで使える同様の仕組みについては、Claude Codeとgit worktree：並行タスクを参照してください。

準備：バージョン、プロジェクトの信頼、コミット#

開始前に3点を確認してください。コマンドは元のプロジェクトのフォルダーから実行します。

まず、Codex CLIのバージョンを確認します。この手順はバージョン0.155.1を対象としています。他のバージョンでは、フラグの動作を個別に確認してください。

codex --version

次に、HEADが既存のコミットを指しているローカルGitプロジェクトが必要です。つまり、リポジトリに少なくとも1つのコミットが含まれていなければなりません。そうでないと、コピー元がありません。

3つ目に、ソースが信頼されている必要があります。プロジェクトが明示的に信頼されていないものとしてマークされている場合、コピーが作成される前に--worktreeでの起動が失敗します。Codex CLIをセットアップしたばかりの場合は、基本的な準備についてCodex（OpenAI）：概要と使い始め方で説明しています。

起動前に、このリポジトリにある既存の作業コピーの一覧を確認してください。起動後に比較するためにも使えます。

git worktree list

別々のフォルダーを使うと、タスクを切り分けて管理できます。エージェントとの作業全般については、Ailootのドキュメントにある実践的な資料が役立ちます。

手順：2つ目のタスク用に別のコピーを起動する#

1. 実験的な機能を有効にして、別のコピーでセッションを開始する

   1つ目のタスクにすでに取り組んでいる、元のプロジェクトのフォルダーからコマンドを実行します。

   codex --enable worktrees --worktree
   

   期待される結果：Codexが現在のHEADからプロジェクトの新しい作業コピーを作成し、その中でエージェントセッションを開きます。コピーは、名前付きブランチが紐付いていないdetached HEAD状態です。バージョン0.155.1では、フラグはこのように動作します。

2. 元のプロジェクトで別のターミナルを開き、作業コピーを再度一覧表示する

   git worktree list
   

   期待される結果：出力に新しいコピーのパスとdetached HEADを示すマーカー（または、ブランチがあればそのブランチ）が追加されます。この一覧はGitがコピーを登録したことを示しますが、エージェントがタスクを完了したことまでは確認できません。ファイルがあることを確かめるには、一覧に表示されたパスのフォルダーを開いて中身を確認してください。

結果を確認して作業を保持する方法#

新しいコピーで2つ目のタスクが終わったら、結果を別途保存して移す必要があります。--worktreeコマンドは変更をメインブランチにマージせず、結果を自動的に移すこともありません。コピーはdetached HEAD状態のままなので、その中でコミットしても、それだけでは新しいブランチは作成されません。コミットを保持する必要がある場合は、コピーのフォルダーを削除する前に、ブランチに紐付けるか、メインプロジェクトに移してください。

結果を保持するまでは、コピーのフォルダーを削除しないでください。作業フォルダーがクリーンであることを確認しても、必要なコミットを保持したことにはなりません。コミットにブランチが紐付いていない可能性があるためです。

異なるツールで複数のタスクを同時に進める場合は、互いに干渉しないよう、あらかじめ方法を計画してください。2つのエージェントを一緒に使う方法については、Claude CodeとCodexを併用するで説明しています。

起動が中断された場合：コピーの場所を確認する#

--worktreeでの起動は、いくつかの理由で失敗することがあります。

• 機能が事前に有効化されておらず、起動コマンドに--enable worktreesが含まれていない：Codexは--worktreeフラグでの起動を拒否します。
• 間違ったフォルダーにいる、またはコミットがない：現在のフォルダーがGitリポジトリでないか、まだコミットが1つも含まれていない場合、コピー元がありません。
• プロジェクトが明示的に信頼されていないソースとしてマークされている：Codexは--worktreeでのセッション開始を拒否します。まず、正しいプロジェクトを開いていることを確認してください。信頼状態を自動的に変更しないでください。

新しく作成されたコピーにセッションを接続できなかった場合、たとえばプロセスが中断された場合でも、作業フォルダーは自動的には削除されません。まず作業コピーの一覧を確認し、何かを削除する前に、そのコピーをまだ使用しているCodex CLIセッションがないことを確かめてください。

git worktree list

フォルダーを開いて、必要な変更を保存してから削除してください。エージェントセッションの起動が完了しなくても、コピーが残っていることがあります。コピーが存在し、もう必要なく、どのセッションも確実に使用していない場合は、元のリポジトリからgit worktree removeを実行し、フォルダーのパスを指定して手動で削除してください。--forceは追加しないでください。コピーに未コミットの変更や未追跡ファイルが含まれている場合、コマンドは削除を拒否します。拒否された場合は、安全策を無効にせず、フォルダーの中身を確認してください。

Codex CLIを更新したら、再度codex --versionを確認し、git worktree listでもう一度確認してください。実験的なフラグはバージョンによって動作が異なる場合があります。

その他の資料とツール：Ailoot。