🍣

Codex Appのチュートリアル：worktreeを使った並列実行まで

に公開
OpenAI
multiagent
Codex
worktree
tech

はじめに：Codex Appとは

OpenAIより、2026年2月2日にmacOS向けに Codex App が新たに公開されました。

すでにCodexやChatGPTがあるなかで、Codex Appの位置付けとはなんでしょうか。

結論から言うと、Codex Appは 「コーディングエージェントを複数運用するための司令塔です。
ChatGPTのように単発相談もしつつ、より重要なのは “タスクをスレッドとして切り、並行に走らせ、差分レビューし、必要に応じてエディタで仕上げる”という、開発の実務フローに寄せた設計になっている点です。

  • ChatGPT：会話中心。コードも書けるが、基本は“対話UI”が主役
  • Codex（CLI / IDE拡張 / Web）：同じエージェントを各環境で使うための入口
  • Codex App：とくに複数スレッドの並列作業・worktreeでの衝突回避・Git差分レビュー を、1つの画面で回すための専用クライアント

つまり、Codex AppはIDEを置き換えるものではなく、複数エージェントを管理するための新たなツールというわけです。

本記事では、Codex Appの主な機能をハンズオン形式で紹介します。

紹介する機能：

  • Modeの切り替え（Local, Worktree, Cloud）
  • Worktreeを利用した並列実行
  • Plan mode

インストール

まだインストールができていない方は、OpenAI Developersの Codex App ページからどうぞ。

https://developers.openai.com/codex/app/

Codex Appの全体像：プロジェクトとスレッドの考え方

Codex Appを理解するうえで、まず押さえるべき基本単位は 「プロジェクト」 と 「スレッド」 です。

プロジェクト（Project）

Codex Appにおけるプロジェクトは、ざっくり言うと 「特定ディレクトリ＝1つのコードベース」 を表します。

スレッド（Thread）

スレッドは 「1タスクの作業履歴・差分・やり取りが集約される単位」 です。
プロンプト→モデル出力→ツール実行→差分、がまとまって残り、スレッドを切り替えることで 複数タスクを並行 に進められます。

また、複数スレッドを同時に走らせられる一方で、同じファイルを複数スレッドが同時に触ると当然ぶつかります。そこで後述する Worktree が効いてきます。

土台のプロジェクトを作ってみる

まず今回のハンズオンの例題として、Exploreにて紹介されているスネークゲームの作成プロンプトを打ってみましょう。

https://developers.openai.com/codex/explore

テキストフィールドの上にこのようなものが表示されていたら、それをクリックでも大丈夫です。

プロンプトを入力して実行しましょう。

すると、実行中は以下のようにどのような思考で、何をしているのかを出力してくれます。

およそ、4分ほどで完成しました。

そのときの画面がこちらです。
Codex Appはおもに、スレッドの画面と、Gitをベースとしたレビュー画面からなります。
そして下にターミナルも開くことができます。

エディター画面がないことにお気づきでしょうか。
Codex Appは、IDEではないので、コーディングはここではしません。
エージェントを管理することに特化しているのですね。

ちなみに、IDEには右上のOpenから移動です。

生成された結果を確認するとこんな感じです。

概ねよくできています。

気になる点もありますが（特に、グリッドの右側と外枠の間のスペース）、
とりあえずコミットしてしまいます。

右上のCommitボタンからできます。

実行モード

続いて、修正と機能追加をしていきたいのですが、その前にモードの説明をします。

Codex Appでは、テキストフィールド左下から実行環境（mode）を選択できます。
各スレッドは必ず1つのmodeで動く、というのがポイントです。途中で切り替えることはできません。

Local

いま開いているプロジェクトディレクトリを直接触る モードです。
変更はそのまま手元の作業ディレクトリに入るため、素早い反復に向きます。

Worktree

Git worktreeを自動で切って、隔離された作業コピー上で変更する モードです。
Localと違って、元の作業ディレクトリ（source）にはすぐ反映されません。
差分を確認してから「取り込む」フローにできるので、並列開発や安全な試行に強いです。

worktreeの詳細は別記事でも解説しています。

https://zenn.dev/fztkm/articles/b3d13d92358acb

Cloud

クラウド上の隔離環境でスレッドを動かす モードです。
クラウド環境側でリポジトリをcloneし、対象ブランチをcheckoutして作業します。
ローカルPCの負荷や状態に依存しないので、「別端末から投げたい」「重いタスクを逃がしたい」などに向きます。

修正はworktreeで試そうと思いますが、

さきほどのスネークゲーム作成のスレッドではデフォルトのlocalで実行しているため、左のパネルからStart new threadしてください。

それでは、このような感じで、修正依頼を投げます。

ちなみにですが、Codex Appのworktreeは ~/.codex/worktrees/ にて作成されます。

そのため、もちろんですがworktree上の変更を確認したいときはそのフォルダを開きましょう。sourceは何も変わってません。

worktreeの一覧は以下のコマンドで見れます。

❯ git worktree list
~/Development/snake_game_codex_tutorial            4ed72b2 [master]
~/.codex/worktrees/8c71/snake_game_codex_tutorial  4ed72b2 (detached HEAD)

結果を確認すると、無事修正できてますね。

OKなので、右上のHand off to localから、変更を元のディレクトリに取り込みましょう。今回は、ApplyでもOverwriteでも大丈夫です。(Overwriteは強制的にworktreeの状態をsourceに取り込むため注意です。)

プランモード

引き続き、ゲームをアップデートしていきたいですが。アイデアがないので、考えてもらいましょう。Plan modeを使います。

このモードを使うと、いきなり実装に入る前に、タスクを分解した実行計画（Plan）を作ることにフォーカスできます。

Codex Appでは、スレッドのコンポーザーから /plan-mode で Plan mode をトグルできます。

適当にプロンプトをうってPlanを立ててもらいます。

途中で以下のような質問をしてくれます。軌道修正をする必要がなくなってよいですね。

出力されたPlanがこちらです。

Snake UIブラッシュアップ + ランキング保存機能 実装計画
## Snake UIブラッシュアップ + ランキング保存機能 実装計画

### Summary
- 現状のシンプルUIを、`Arcade ネオン` テーマに刷新して視認性と操作体験を改善する。
- 新機能として `localStorage` ベースのハイスコア保存を1つ追加する（今回スコープ: UI + 1機能）。
- 既存ゲームロジック（移動/当たり判定/得点）への影響を最小化し、表示層と永続化層を中心に拡張する。

### 実装方針（決定済み）
1. UIを「ゲームカード」構成に再レイアウト
2. HUDを情報ブロック化（現在スコア、ハイスコア、状態、操作ボタン）
3. グリッドの見た目をネオン調へ変更（セル、蛇、餌、外枠、フォーカス）
4. ハイスコアの保存・読込・更新を `main.js` に追加
5. ロジック単体テストは既存維持 + 永続化のユニットテストを追加（純関数化してテスト可能にする）

### 変更対象ファイル
- `~/.codex/worktrees/8c71/snake_game_codex_tutorial/index.html`
- `~/.codex/worktrees/8c71/snake_game_codex_tutorial/src/styles.css`
- `~/.codex/worktrees/8c71/snake_game_codex_tutorial/src/main.js`
- `~/.codex/worktrees/8c71/snake_game_codex_tutorial/tests/gameLogic.test.js`（既存維持）
- `~/.codex/worktrees/8c71/snake_game_codex_tutorial/tests/main.storage.test.js`（新規）

### 重要な公開インターフェース変更
- 追加DOM要素（`index.html`）
  - `#high-score`（ハイスコア表示）
  - 必要に応じて HUD 内ラッパー要素（情報列/ボタン列）
- 追加ストレージキー（`main.js`）
  - `snake.highScore`（数値文字列）
- 追加関数（`main.js` 内、必要なら `src/storage.js` へ分離）
  - `loadHighScore(storage = localStorage): number`
  - `saveHighScore(score: number, storage = localStorage): void`
  - `syncHighScore(currentScore): number`（現在値と保存値を比較して更新）

### 詳細タスク
1. `index.html` のHUDを再構成  
- `Score` と `High Score` を並べて表示。  
- `status` はラベル表示を維持。  
- `Pause` / `Restart` は操作群としてまとまるようマークアップ調整。

2. `styles.css` の全面調整（Arcade ネオン）  
- カラートークンを `:root` に変数化（背景、ネオン主色、警告色、文字色）。  
- 背景を単色からグラデーション + 光彩アクセントへ変更。  
- コンテナにガラス風カード（半透明、境界線、シャドウ）適用。  
- グリッド境界を強調、セル境界を弱めて盤面視認性向上。  
- `snake-head` を本体より明るくして進行方向を認識しやすくする。  
- ボタンは hover/active/focus-visible を定義。  
- モバイル（`<700px`）とデスクトップ（`>=700px`）で余白・文字サイズを最適化。

3. `main.js` にハイスコア保存ロジック追加  
- 初期化時: `loadHighScore` 実行し `#high-score` に反映。  
- 毎tick後または`setStatus`内で `state.score` を監視し、超過時に保存・反映。  
- `restart` ではハイスコアは維持、現在スコアのみ初期化。  
- 不正値・例外（`localStorage`不可）時は `0` にフォールバックしてゲーム継続。

4. テスト追加  
- 新規 `tests/main.storage.test.js` で storage関数を検証。  
- モックstorageで以下を確認:
  - 初期未保存時 `0` を返す
  - 数値保存/読込できる
  - 現在スコアが高い時だけ更新される
  - 不正値（`"abc"`）で `0` フォールバック

5. 最終確認  
- `npm test` が全件成功。  
- 手動確認: 開始→加点→ゲームオーバー→再起動でハイスコア維持。  
- 手動確認: モバイル幅/デスクトップ幅でレイアウト崩れなし。

### テストケースとシナリオ
1. 正常系
- スコア0開始、餌取得でスコア上昇、ハイスコア更新表示。
- リロード後もハイスコアが保持される。
2. 境界系
- ハイスコア同値/未満では保存値が更新されない。
- `localStorage` が空・欠損でもクラッシュしない。
3. 退行防止
- 既存 `gameLogic` テスト（移動、逆入力無効、成長、壁衝突、自己衝突、餌配置）が全て通る。

### Assumptions / Defaults
- 追加機能は「ハイスコア保存」のみ（難易度変更・障害物は今回対象外）。
- 保存先はブラウザ `localStorage` 固定。
- UIテーマは `Arcade ネオン` 固定。
- i18n対応は今回行わず、既存英語ラベルベースを維持（必要なら次フェーズで日本語化）。
- 外部ライブラリは導入しない（現行のVanilla JS/CSS構成を維持）。

いい感じに、タスクが定まったので、これを実行していきます。

その前に並列でエージェントを動かして実装しようと思うので、タスクを分解してもらいます。

これらを２つのエージェント（AとB）で並列実行したいので、実装範囲が被らないように、チケットに分解して。

このプロンプトを投げて、切り分けてもらいました。

チケットAとBの切り分け
## チケットA（Agent A）: UIブラッシュアップ（Arcadeネオン）
**担当範囲（このファイルのみ）**
- `snake_game_codex_tutorial/index.html`
- `snake_game_codex_tutorial/src/styles.css`

**実装内容**
1. HUDを情報ブロック化（`Score` / `High Score` / `Status` / 操作ボタンの見た目整理）
2. ネオン調テーマ適用（背景、カード、グリッド、ボタン、フォーカス）
3. モバイル/デスクトップのレスポンシブ調整
4. `#high-score` 表示用要素をHTMLに追加（見た目のみ。ロジックは触らない）

**受け入れ条件**
- レイアウト崩れなし（モバイル/デスクトップ）
- 既存操作（Pause/Restart/方向ボタン）が見た目変更後も使える
- JSロジックファイルは変更しない

---

## チケットB（Agent B）: ハイスコア保存機能
**担当範囲（このファイルのみ）**
- `snake_game_codex_tutorial/src/main.js`
- `snake_game_codex_tutorial/src/storage.js`（新規）
- `snake_game_codex_tutorial/tests/main.storage.test.js`（新規）

**実装内容**
1. `localStorage` 読込/保存の純関数を `storage.js` に実装
2. `main.js` にハイスコア表示・更新連携を実装（`#high-score` を参照）
3. 例外/不正値フォールバック（保存不可時は0）
4. ストレージ関数のユニットテスト追加

**受け入れ条件**
- スコア更新でハイスコアが正しく更新される
- リロード後もハイスコア維持
- `npm test` 全件成功
- HTML/CSSは変更しない

---

## 衝突回避ルール（重要）
1. `main.js` は **B専有**  
2. `index.html` と `styles.css` は **A専有**  
3. AはJS変更禁止、BはHTML/CSS変更禁止  
4. マージ順はどちら先でも可（ファイルが分離されているためコンフリクトしない）

Worktreeを複数開いて安全に並列実行

それでは、エージェントAさんとBさんにそれぞれチケットを割り振って実行してもらいます。

  • Aさんは、現在とおなじworktreeで引き続き作業してもらいます。
  • Bさんは、threadを新規作成してあらたにworktreeを作り、そこで作業してもらいます。

Aさんには、そのままAを頼むプロンプトを実行

Bさんには、コンテキストがないので、実装計画とチケット割りふりをまず理解してもらった後で実行します。

復習ですが、新規Threadで最初のプロンプトを打つと、worktreeが新規作成されます。

❯ git worktree list
~/Development/snake_game_codex_tutorial            4ed72b2 [master]
~/.codex/worktrees/8c71/snake_game_codex_tutorial  4ed72b2 (detached HEAD)
~/.codex/worktrees/c376/snake_game_codex_tutorial  4ed72b2 (detached HEAD)

Aの結果：AにはUIを頼んだので、ネオンなテーマに修正されました。

ただし、ロジックはスコープ外であるため、High Scoreは0のままで更新されていません。

Bの結果：BはUIの実装を頼んでいないので、なにも変化がないです。しかし、storage.js などのロジック関連のファイル修正が行われています。

よさそうなので、両方ともHand off to localからlocalにApplyします。

すると、結果はこちらです。

ちゃんとHigh scoreが更新されるようになっていますね。

まとめ

Codex Appは、単なる「コード生成UI」ではなく、複数エージェントを上手に運用するためのツールでした。

総括しますと、Codex App を使うことで、以下のような特性を持ったワークフローが自然と生まれるのです。

  • Project / Thread によって、タスクとコンテキストが自然に整理される
  • Local / Worktree / Cloud のmodeで、速度・安全性・並列性のバランスをスレッド単位で選べる
  • Worktree を使うと、同一リポジトリ上でも衝突を避けて並列実行ができる
  • Plan mode は、実装前にタスク分割・並列化の起点として特に相性が良い

Discussion