Codex CLI 0.154.0のworktree実践術：隔離から統合まで

Codex CLIでworktreeを最短で始める

必要なのは、Codex CLI 0.154.0、ローカルのGitリポジトリ、そして有効化した実験的なworktrees機能です。古いバイナリには存在しないフラグを探すことにならないよう、最初にバージョンを確認します。

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

この設定コマンドを実行すると、機能の選択内容がCodexの設定に保存されます。一度だけ試すなら設定は変更せず、その実行時に--enable worktreesを加えます。

用途に応じて、新しい隔離セッション、ヘッドレスのタスク、または既存の会話から分岐したセッションを起動できます。

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

対話セッションを分岐する場合、<session-id>には/statusで表示されるチャットIDを指定します。バージョン0.154.0ではIDの明示が必須で、codex fork --worktree --lastは受け付けられません。

同じ操作はターミナルUIからも行えます。/worktreeと入力すると、現在の会話を新しいチェックアウトで続けるか、そこで新規会話を始めるか、このリポジトリですでにCodexが管理しているworktreeを参照するかを選べます。

Codexが作成するチェックアウト

管理対象のworktreeは、同じGitリポジトリにひも付く別のチェックアウトです。ひとつの蔵書目録を、ふたつの閲覧室で共有するイメージです。各部屋では別々のページを広げられますが、参照するコミットとブランチは共通です。

Codexは、元リポジトリでコミット済みのHEADから新しいチェックアウトをdetached HEAD状態で作り、新規セッションに結び付けます。detached HEADでは名前付きブランチを動かすのではなく、チェックアウトがコミットを直接指します。元のチェックアウトの位置は変わりません。

クリーンな状態から始まるため、注意すべき点があります。元のチェックアウトにある未コミットの編集内容は、新しいセッションには引き継がれません。一般的な.envやnode_modulesディレクトリのような無視対象ファイルも同様です。OpenAIは、Desktopが管理するローカルworktree向けに.worktreeincludeによるコピーを案内していますが、コマンドラインで作成したworktreeは明確に対象外です。CLIでは、タスクに必要なものを別途準備する前提で進めます。

リポジトリ内の深い階層からCodexを起動した場合、管理対象チェックアウトでも相対的な位置が保たれます。たとえばapps/webから開始すると、コミット済みのリビジョンにそのディレクトリが存在する限り、新しいworktree内の対応するapps/webにセッションが置かれます。

起動から成果を残すまでの実践フロー

安全に進める要点は、開始時の状態を整え、移動先を確かめ、作業し、根拠を確認してから、残すか破棄するかを明示的に決めることです。

1. 本当に使いたいコミットから始める

--worktreeはブール型のスイッチであり、ブランチやベースを指定するオプションではありません。対象リポジトリのHEADを起点にします。起動前に目的のベースブランチへ切り替え、タスクに必要な元側の変更はコミットしておきます。特定のローカルチェックアウトをCodexに指定するには-C <repo-path>を使えます。

タスクが独立しているなら新規セッションが向いています。新しい試行にも元の会話で決めた内容や制約が必要なら、forkを選びます。forkは会話履歴を新しいチャットへ引き継ぎながら、作業だけを隔離されたチェックアウトへ移すため、最初の試行を比較用にそのまま残せます。

2. 編集前にチェックアウトを確認する

開始時にCodexへpwd、git status --short、git rev-parse --short HEADを実行させます。作業ディレクトリが管理対象のパスであり、ステータスがクリーンで、コミットが意図した元のHEADと一致していることを確認します。

この確認だけで、優れた作業を誤ったベース上で進めてしまう、地味ながら損失の大きいミスを防げます。

3. その作業レーンに必要なものだけを導入する

worktreeが隔離するのは、チェックアウトされたファイルです。コンテナを作ったり、ポートを予約したり、データベースを複製したり、依存関係をインストールしたりする機能ではありません。管理対象チェックアウトの中で、そのリポジトリ標準のセットアップコマンドを実行します。衝突し得るリソースについては、並列セッションごとに別々のポート、一時データベース、キャッシュディレクトリ、テストアカウントを割り当てます。

ここが最も重要な制約です。Gitの差分がどちらもクリーンでも、両方のセッションが同じ開発用データベースを移行したり、同じポートを使おうとしたりすれば、互いに干渉します。

4. 差分を確認し、正しいスレッドを再開する

worktreeのセッション内では、/reviewで未コミットの変更を確認できます。別のターミナルから調べる場合は、まず/worktreeを開き、Browse worktreesで対象チェックアウトを選び、Copy working directoryを実行します。その後、git -C "<worktree-path>" status --short、git -C "<worktree-path>" diff --stat、git -C "<worktree-path>" diffを実行します。

codex review --worktreeは実行しないでください。バージョン0.154.0では、このフラグの組み合わせは拒否されます。実行中のworktreeセッション内からレビューするか、コピーしたパスを通常のレビューツールに指定します。

後から続けるときは、/worktreeでBrowse worktreesを開き、管理対象チェックアウトを選んでResume owner threadを実行します。codex resumeに--worktreeを追加してはいけません。再開時は、新しいworktreeを割り当てるのではなく、すでにセッションと結び付いたチェックアウトへ戻る必要があります。

5. チェックアウトを片付ける前に変更を残す

採用する変更は、該当するテストを実行し、worktree内でコミットして、そのコミットSHAを控えます。元のチェックアウトではgit cherry-pick <sha>を使い、現在のブランチへコミットを取り込みます。detached状態のコミットに永続的な移動先を与えるため、worktreeを削除する前にcherry-pickしてください。

変更を独立したレビューブランチにするなら、worktree内でgit switch -c codex/<task>を実行し、コミット、push、プルリクエスト作成まで進めます。Gitでは、同じブランチを元のチェックアウトとworktreeで同時にチェックアウトできません。worktree側からpushするか、worktreeを削除してから別の場所でそのブランチをチェックアウトします。

CLIで作ったworktreeは自動で削除されません。変更が安全にコミットされたか、意図どおり破棄できる状態になったら、チェックアウトがクリーンであることを確認し、元リポジトリからgit worktree remove <worktree-path>を実行します。--forceは避けます。git worktree pruneは後で古いGit登録を消すために使えますが、まだセッションがチェックアウトを所有していないか確かめる代わりにはなりません。

worktree導入でコストはどう変わるか

標準機能になったことで、小さいながら繰り返し発生していたシェル操作を省けます。0.154.0より前のCLIでは、パスを作り、ブランチを作成またはdetached状態にし、そのディレクトリでCodexを起動し、どのチャットと対応するか覚え、最後にGitとセッションの両方を片付ける必要がありました。新しいフラグは、起動時にチェックアウトの作成とセッションへのひも付けをまとめて行います。さらに/worktreeから、リポジトリを認識した一覧表示と再開ができます。

既存のCodex契約者に対して、チェックアウト専用の料金は別途公表されていません。Codex Plusは月額$20です。並列worktreeを整理する商用エージェントワークスペースのUnstoppableは、有料Proプランが月額$19からで、Businessはユーザーあたり$29、Enterpriseはユーザーあたり$49です。ネイティブ対応したCodexなら、すでに利用中のサブスクリプション内で、チェックアウト作成と再開という限定的な用途をまかなえます。

ただし、有料ワークスペースが担う残りの機能まで置き換えるものではありません。複数エージェントを横断するダッシュボード、ポート割り当て、共有環境のセットアップ、テスト結果の集約、プルリクエスト追跡、チームポリシー、コストレポートは、依然として素のチェックアウトより上の層にあります。並列セッションも同じCodex利用枠を使います。費用面での正しい捉え方は「並列開発が無料になった」ではなく、「隔離だけを目的に購入していたなら、オーケストレーションツールを減らせる可能性がある」です。

この機能を含む製品全体を知りたい場合は、ローカルCLIとエージェントの流れを扱ったCodexレビューが参考になります。以前のCodex CLI 0.152.0解説では、ターミナル操作を自動化するときに、リリース固有の制約がなぜ重要なのかを説明しています。

効果が大きい順：worktreeが向く七つの仕事

1. リスクの高い依存関係アップグレード

メンテナーは、フレームワーク、パッケージマネージャー、テストランナーの更新専用にworktreeを起動できます。Codexにロックファイルや設定を編集させ、メインのチェックアウトで進行中の機能開発を汚さずにフルテストを実行できます。成果はレビュー可能な更新レーンにまとまり、stashや無関係な編集のロールバックなしで破棄できます。

2. 同じ機能を異なる方針で実装

テックリードは、同じ計画の会話をふたつの管理対象worktreeへforkし、一方には最小限のパッチ、もう一方には構造から見直す案を依頼できます。差分の大きさ、テスト、移行リスクを比べれば、後の試行で先の成果を上書きすることなく、根拠に基づいて選べます。

3. 製品開発と並行したバグ調査

機能開発の途中にいるプロダクトエンジニアでも、コミット済みのHEADからクリーンなworktreeを作り、本番バグを再現できます。未完成の機能には触れず、そのレーンだけでCodexに計測、テスト、修正を進めさせられます。緊急時のstashを減らし、hotfixの差分も明瞭にできます。

4. 大規模なcodemodとリファクタリング

プラットフォームチームは、広範囲の名前変更やAPI移行を専用チェックアウトに分け、そこでフォーマッターとテストを動かせます。メインブランチに入れる前に、変更対象となったファイル一式を確認できるため、生成された大量の差分をコミットに値すると判断するまで隔離できます。

5. レビュー修正専用レーン

プルリクエストの作成者は、レビューのベースをコミットしてその状態から隔離されたCodexセッションを起動すれば、ローカルで開いている別ブランチを乱さずにレビューコメントへ対応できます。準備が整った時点でworktreeからpushでき、修正だけに集中したコミット列を保てます。

6. 再現可能なメンテナンス実行

ビルドエンジニアは、生成ファイルの更新や不安定なテストの調査といった限定的な作業にcodex exec --worktreeを使えます。ヘッドレス実行では、追跡対象ファイルがクリーンなチェックアウトと、後から確認できる永続セッションが得られます。メインの作業ツリーで何を開いていても、意図しない混入を抑えられるのが利点です。一方で、自動化側が依存関係のセットアップと後片付けを担う必要があります。

7. 安全なリポジトリ探索

新しくチームに加わった人は、普段使うチェックアウトに触れる前に、Codexへ未知のコードベースを整理させ、管理対象worktree内で小さなドキュメント変更やテスト変更を試せます。技術面だけでなく心理面でも、探索の境界が見え、簡単に破棄できることが利点です。

残された課題を狙う三つのプロダクト案

1. 最有力：worktree準備レイヤー

新しい管理対象チェックアウトを、実行可能で衝突しないタスクレーンへ変える小さなローカルツールです。プロジェクトの技術構成を判定し、承認済みの依存関係セットアップを実行し、ポートを割り当て、一時データベースまたはスキーマを作成します。さらに、選択した秘密情報だけを公開し、ヘルスチェックを行い、対応するクリーンアップ手順を表示します。

需要の裾野は広く、git worktreeは米国Googleで月間約9,900回、what is a git worktreeも月間590回ほど検索されています。Codexのネイティブ機能はチェックアウト作成を解決しましたが、実行環境の準備は手つかずです。そのため、これが最も有望な機会です。

販売可能な最小構成に必要なのは、リポジトリ用マニフェスト、セットアップと終了処理のコマンド、ポート予約、環境ファイルのテンプレート化、ステータス確認です。ただし、セキュリティ上の懸念があります。秘密情報をコピーしたり、複数エージェントを同じデータベースへ向けたりするツールは、解消する以上のリスクを生む可能性があります。OpenAIが将来、標準のライフサイクルフックを追加すれば、機会自体が狭まる点にも注意が必要です。

2. エージェント横断のレーンダッシュボード

複数のリポジトリやツールにまたがるworktreeを見つけ、所有セッション、ブランチまたはdetached状態、変更ファイル、テスト結果、Codex使用量、プルリクエスト、ディスク使用量を一覧化するデスクトップまたはターミナル向けダッシュボードです。安全な再開とクリーンアップ操作も提供します。

git worktree claude codeは米国で月間約480回、完全一致のparallel coding agentsは月間10回ほど検索されています。後者は小さな数字ですが、支払い行動はすでに見えています。並列エージェントworktreeを含むUnstoppableは月額$19からです。想定する購入者は、Codex、Claude Code、通常のターミナルをすでに併用している開発者です。

MVPは読み取り専用でも成立します。Git worktreeを列挙し、既知のセッションメタデータと照合し、必要に応じてステータスやテストのコマンドを実行し、各エージェントへ戻るディープリンクを用意します。ただし、標準機能との競争は避けられません。Codex 0.154.0は自ら管理するworktreeをすでに一覧表示できるため、エージェントを横断した可視性、実行時状態、チーム向けレポートで差を付ける必要があります。

3. 統合とクリーンアップのゲート

完了したエージェントの作業レーンとメインブランチの間に置くガードです。ステータスがクリーンか確認し、必須テストを実行し、ほかの稼働中worktreeが変更したファイルを検出します。さらに、cherry-pickの順序を提案し、未統合のコミットが残っている間は破壊的なクリーンアップを拒否します。

その需要は検索語にも表れています。git remove worktreeは米国で月間約390回、git worktree vs branchは320回、git worktree pruneは140回です。いずれも、隔離された作業を共有の成果へ変える局面に集中しています。

MVPは、ローカルGitコマンドと小さなポリシーファイルで構成できます。自動でコードを一行も編集しなくても価値を出せます。ただし、配布面には課題があります。GitクライアントやCIベンダーも同じチェックを追加できるため、独立したツールとして成立させるには、複数のコーディングエージェントと整っていない現実のリポジトリに対する優れた対応が欠かせません。

採用判断を左右する制約

ファイルの隔離が課題なら、ネイティブworktreeは有効です。ただし、実行環境全体を隔離する機能だと誤解してはいけません。

このリリースには、DesktopアプリのHandoffボタンに相当するCLI機能もありません。コードを元へ戻す方法は、引き続きGit上で判断します。コミットしてcherry-pickする、ブランチをpushする、または破棄して削除する、という選択です。この明示的な工程には意味があります。隔離が有効なのは、意図しない変更がメインのチェックアウトへ流れ込まないからです。

次の一手として、重要度の低い依存関係アップデートをひとつ選び、codex --enable worktrees --worktreeで実行します。コピーしたチェックアウトのパスから差分とテストを比較し、採用するコミットだけをcherry-pickしてからworktreeを削除してください。リポジトリに合わせた信頼できる隔離エージェント環境が必要なら、本番運用の仕組みづくりをお手伝いできます。