Agent Controller（kakizaki-agent-controller）

複数リポジトリで並列に動く Claude Code / Codex のセッションを、1 つの VS Code ウィンドウで俯瞰・整理・起動するための VS Code 拡張。

チャット画面は自作せず、公式の Claude Code 拡張・Codex 拡張のチャットをそのまま開く。Agent Controller が担うのは、一覧・状態・整理・新規作成・通知・残量表示である。

できること

• 一覧: 全リポジトリの Claude / Codex セッションを 1 画面に並べ、リポジトリ名・名前・状態（作業中／承認待ち／入力待ち／上限待ち／エラー／完了／終了／不明）を表示する。一覧の幅が十分に広いときだけ、状態の左隣に最終やり取りの日付（常に YYYY/M/D。並び順と同じ時刻）を出す。幅が狭いときは、タイトル・状態・ピンの 3 つだけを出す（種別・リポジトリは行のツールチップで確かめられる）。
• 開く・戻る: 行をクリックすると、同じウィンドウ内の一覧の右側（右隣のエディタグループ。無ければ一覧の右に作り〔向きは設定 workbench.editor.openSideBySideDirection に従う〕、以後も同じグループ）に公式拡張のチャットが開く。ctrl+alt+d で一覧へ戻る。
• 会話の続行先を切り替える: 行の三点メニューから「Codex で続ける」「Claude で続ける」を選ぶと、会話の続きを相手側へ移して右側で開く。往復しても一覧は同じ 1 行のまま、名前と固定を保つ。直近の発話・応答はそのまま移し、ツールの実行は要点にする。長い会話は古い部分を相手側の AI で要約する（その場合は利用量が発生する）。
• 新規作成: どのエディタタブでも右上のタイトルバーにある二つのアイコン（Claude・Codex）から、開くリポジトリを選んで公式 Claude / Codex のチャットを開く（名前・パスで絞り込み、最近使った順、「フォルダを選択…」で任意のフォルダ）。Codex は PDN も要らず、選んだフォルダがそのまま作業フォルダ（cwd）になる。Claude の新規起動に hub や PDN は要求しない（PDN が無いときは選ばずに公式の空エディタを開く）。
• 題: 公式が題を付けない「(無題)」のセッション（既存・本拡張が作った新規・スラッシュコマンドで始めたもの）に、AI が作った題を後から付ける。公式の自動題と同じ仕組み（Claude は公式 CLI、Codex は同梱 codex）で 1 セッションにつき 1 回だけ作り、公式のタブ・履歴と同じ場所に保存する。利用者が付けた名前は上書きしない。開いているタブは、開き直すと新しい題になる。設定 agentController.aiTitle.enabled で止められる。
• 整理: 固定したセッションを常に上部へ置く。固定している行・していない行のそれぞれで、最後にチャットが投稿された（利用者が最後に発話した）順に並ぶ。エージェントの応答・ツールの実行・状態の変化では順は動かず、手動の並び替え（ドラッグ）は無い。名前・固定は保存される（名前の変更は一覧の表示名だけで、公式側の名前は書き換えない）。
• 通知: 承認待ち・入力待ち・本当の完了・エラーを知らせる。VS Code が前面なら VS Code 内通知、前面でなければ macOS の通知（任意）。通知のクリックで該当セッションが開く。
• 残量: アカウントごとのトークン残量（5 時間枠・週次枠）を一覧の上に表示する（任意）。

仕組み（概要）

• （任意）各リポジトリを 1 つの hub フォルダの .claude/worktrees/<repo> に置き、hub を VS Code で開くと、1 ウィンドウで複数リポジトリを扱える。公式拡張はこの配置のセッションを各リポジトリで動かす。hub が無くても一覧・開く・新規作成は使える。
• Claude Code / Codex の hooks から起動される小さな Node スクリプトが状態を判定してファイルへ書き、OS 通知を出す。拡張はそのファイルを読んで一覧へ反映する。VS Code を閉じていても通知は出る。hooks が無くても、一覧・開く・新規作成は動き、状態は記録ファイルと稼働状況から推定する。Codex は信頼されていない hooks を実行しないため、「hooks を設置」の確認（差分表示・バックアップ付き、1 回のモーダル）のうえで、本拡張の hooks だけを信頼する（Codex の /hooks での承認と同じ記録）。
• 公式拡張の公開されていない挙動に依存している。依存の一覧と検査方法は docs/CONTRACTS.md。

注意: 進行中のチャットタブを閉じると、そのセッションの作業が中断する（実行中のツールも止まる）。一覧へ戻るときはタブを閉じず、ctrl+alt+d を使う。詳しい制約は docs/SETUP.md の「使い方の制約」。

詳しくは docs/ARCHITECTURE.md。

インストール

VS Code Marketplace・Open VSX には未公開で、GitLab の Releases で .vsix を配布している。次のどちらかで入れる。どちらも VS Code のコマンド code を使う（PATH に無ければ、VS Code のコマンドパレットで「Shell Command: Install 'code' command in PATH」〔日本語表示では「シェル コマンド: PATH 内に 'code' コマンドをインストールします」〕を実行する）。

(a) npm のインストーラ CLI（npx）

npx @jumpohashimoto/agent-controller                   # 最新の Release の VSIX を取得・照合して入れる
npx @jumpohashimoto/agent-controller --version 0.2.0   # 入れる拡張の版を指定する
npx @jumpohashimoto/agent-controller@0.1.0             # インストーラ CLI 自体の版を固定する
npx @jumpohashimoto/agent-controller --help

• 下の (b) と同じ Release から VSIX と SHA256SUMS を取得し、SHA-256 が一致したときだけ code --install-extension で入れる。一致しなければ VSIX を削除して失敗する。
• code が見つからない・インストールに失敗したときは、検証済みの VSIX を一時ディレクトリに残し、その場所と手で入れる手順を表示して失敗する（終了コードは 0 以外）。
• 必要なもの: macOS または Linux、Node.js 22 以上。
• 接続先は https の gitlab.com だけ（リダイレクト先も同じ）。SHA256SUMS は VSIX と同じ Release から取得するもので、署名による検証ではない（転送中の破損や取り違えは検出できるが、配布元自体の改ざんは検知できない）。
• この CLI は拡張を入れるだけで、hooks の設置・設定ファイルの書き換えはしない。詳しくは src/npm-cli/README.md。

(b) Releases から手で入れる

https://gitlab.com/jumpohashimoto/kakizaki-agent-controller/-/releases

1. 使う版の Release から kakizaki-agent-controller-<version>.vsix と SHA256SUMS をダウンロードし、同じディレクトリに置く。
2. そのディレクトリで shasum -a 256 -c SHA256SUMS を実行し、OK と表示されることを確かめる（shasum が無い Linux では sha256sum -c SHA256SUMS）。OK 以外ならその VSIX を入れない。
3. code --install-extension kakizaki-agent-controller-<version>.vsix を実行する（または VS Code の拡張ビューの「…」→「VSIX からのインストール...」で選ぶ）。

更新するときも同じ手順で新しい版を入れる（上書きされる）。hook スクリプトが変わる版では、CHANGELOG.md にその旨を書いている。その場合は更新後に「hooks を設置」を実行し直して、設置済みの hook スクリプトを新しい版にする。

はじめかた（インストールするだけ）

1. 拡張をインストールする（上の「インストール」）。
2. 左の Agent Controller アイコンをクリックする（またはコマンドパレットの「Agent Controller: 一覧を開く」）。

これだけで、一覧の表示・セッションを開く・新規作成が使える。hub 構成（下の「仕組み」）・環境変数・設定ファイルの編集は不要で、フォルダを 1 つ開いただけのウィンドウでも動く。公式の Claude Code 拡張・Codex 拡張は片方だけでも、どちらが無くても拡張自体は起動する（無い側の「開く」「新規作成」は、拡張が無い旨を知らせて何もしない）。

インストール直後に使えない機能（公式拡張が無い・hooks が未設置・PDN が無い など）があれば、起動時に一度だけその内容を通知する（内容が変わらない限り繰り返さない。全文は出力パネル「Agent Controller」）。承認待ち・入力待ちの検知と通知に使う hooks は、通知の「hooks を設置」から、差分を確認してから入れる（設定ファイルを黙って書き換えない）。構成管理ツール等が hooks をラッパー経由で配布済み（本拡張のスクリプトを呼ぶ hook が全エントリ揃っている）なら、設置済みとして扱い、案内もスニペットも出さない（docs/SETUP.md §4）。

詳しい前提と、無いときの動作の一覧（監査表）は docs/SETUP.md の「インストールだけで使える範囲」。

必要なもの:

• VS Code 1.100 以上（信頼されたワークスペース）
• 公式の Claude Code 拡張、Codex 拡張（片方でも、どちらが無くても起動する）
• Node.js 20 以上（hooks を設置するときだけ。PATH に無ければ設定 agentController.hooks.nodePath）
• macOS（OS 通知を使う場合のみ。Windows では hooks の自動設置に対応していない）

hub 構成で運用する場合は docs/SETUP.md の §2 以降に進む。

使い方

左アクティビティバーの「Agent Controller」アイコンをクリックすると、メインエリアのエディタータブに一覧を開く。コマンドパレットの「Agent Controller: 一覧を開く」または ctrl+alt+d でも開ける。開いている一覧タブがあれば再表示する。

一覧タブを開いたままウィンドウを再読み込みすると、同じ場所へ復元する。一覧は変化を検知して自動更新し、見えている間は 10 秒ごとにも取り直す（非表示の間は止まり、再表示で即時に更新する）。手動の再収集はパレットの「一覧を更新」で行える。サブエージェントのセッションと、他のエージェントやプログラムが起動したセッション（codex exec、外部アプリが app-server で作った Codex スレッド、SDK が駆動した Claude セッション、一時ディレクトリや統合テストの作業場所で動いた試験・自動操作のセッション）は一覧と通知から除外する。判別は「対話の正の印」で行い（Codex は thread_source が user など）、新しい形の起動元は隠す側に倒す（設定は不要。旧設定 agentController.codex.hiddenOriginators は廃止し、残っていても無視する。docs/SETUP.md §7）。利用者が自分で開いた対話のセッション・チャットは、作業フォルダ（hub の外を含む）・件数・期間にかかわらず必ず一覧に出す。一度一覧に載せたセッションは「セッション台帳」（状態ディレクトリの session-ledger.json）に記録し、元の履歴が消えても「記録なし」と表示して残す（固定したセッションも消えない）。Claude の履歴は projects/ 配下のすべてのディレクトリを読む（PDN 導入前の旧い名前の場所も含む）。公式の Claude 拡張が開けない場所の履歴を開くときは、公式が読む場所（PDN があれば projects/<PDN>/、無ければ先頭フォルダ由来のディレクトリ）へ複製してから開く（元は変えない。複製側の cwd は symlink 経由の旧パスなら実パスへ直す）。ただし作業フォルダ（cwd）が hub の外にある履歴は、公式拡張が先頭フォルダで再開してしまうため、そのフォルダを新しい VS Code ウィンドウで開いて、そこでセッションを開く（フォルダが無いときは理由を示して開かない）。

一覧の行から開くセッション（Claude・Codex）は、一覧の右隣のエディターグループへ開く（右隣が無ければ一覧の右に新しく作り、以後も同じグループ。Codex が別のグループで既に開いていれば、そのタブを動かさず前面にする。Claude を一覧と同じグループで開いていた場合は、開いた直後に右のグループへ移す。新しいグループの向きは VS Code の設定 workbench.editor.openSideBySideDirection に従うので、down にしていると一覧の下にできる）。タイトルバーのアイコンから新規作成したClaude・Codexは、押したエディタのグループへ開く（エディタが複数のグループにあっても、押したグループを推定して開く。同じ表示のグループが複数ある場合はアクティブなグループ。一覧タブのボタンは、別のグループに公式 Claude のチャットがあっても一覧のグループへ開く。コマンドパレット・キーバインドは、一覧が開いていれば一覧のグループ、無ければアクティブなグループ。docs/CONTRACTS.md C13）。既存タブ・記憶済みタブ・サイドバーは公式の再利用位置を保持する。タイトルバーの公式ロゴ素材の出所・権利は 第三者素材の注記 を参照。

アイコンから開くと左サイドバーは折り畳まれる。起動しただけでは一覧を開かないが、VS Code がアイコン用ビューを表示状態で復元した場合は一覧も開く。

設定（agentController.*）は docs/SETUP.md §7。

切り替えるには、両側の公式拡張と元の会話記録、存在する作業フォルダが必要。Codex への切り替えには同梱 codex の実行ファイル、Claude への切り替えには PDN と公式 Claude が起動できるフォルダも必要。作業中・承認待ち・入力待ちの会話は切り替えられない。失敗したら通知の「再試行」からやり直せる。

相手側のチャットが開いているときは、安全に書き足せないため新しいセッションへ作り直す。Claude は元のタブを閉じると次回は書き足せる。Codex はタブを閉じても最大 3 時間ほどスレッドを保持するため、作り直しになることがある（通知の「古いタブを閉じる」で以前の Codex タブを閉じられる）。以前のセッションは公式の履歴に残るが、本拡張では同じ会話の中へまとめる。古いタブで続けた分も次の切り替えで取り込まれるが、追加先は会話の末尾になる。画像・添付の実体やツールの実行状態は移さない。

状態・通知の対応（Claude と Codex）

一覧の状態と通知は、Claude と Codex で同じ意味になるようにそろえている。ただし、元になる情報が公式拡張・CLI の仕様で異なるため、次の差は埋められない（一覧の上部・行のツールチップにも同じ旨を出す）。

• Codex の hooks が未設置または未信頼のときは、一覧の上部に 1 行の案内を出す（「hooks を設置」、または Codex の /hooks で信頼）。
• Codex が失敗したターンで Stop・notify を出すかは、実機で未確認（出さないときも、一覧は rollout から「上限待ち」「エラー」になるが、通知は出ない）。
• 一覧の「最終やり取り日」は、一覧の並び順と同じ時刻（最後に利用者がチャットへ投稿した時刻。まだ投稿が無い会話は作成時刻）の日付。元データが無い行は、台帳に控えた同じ時刻を出す。切り替えて続ける会話は、現役のメンバーのうち新しい方の時刻を出す。時刻が分からない行は空欄。
• Claude の残量は公開の取得手段が無く、外部のデータ源（設定 agentController.usage.claudeSnapshotPath）が要る。残量欄が出ているのに Claude が無いときは、欄の中にその旨を出す。Codex の残量は、既定の CODEX_HOME と agentController.codex.extraHomes のそれぞれについて取る。
• 公式の Codex でアーカイブしたスレッド（公式の一覧から外れている）は、一覧から消えず「削除済み」と表示する（公式の UI で復元すると元に戻る）。

注意

• hub を開く構成では、各セッションの読み書き範囲に hub 配下の全リポジトリが入る（docs/SETUP.md の「副作用」）。
• 公式拡張の更新で依存している挙動が変わることがある。npm run contracts:check で確認できる。
• OS 通知は macOS のみ。
• 状態ディレクトリ（既定 ~/.local/state/kakizaki-agent-controller）とその中の metadata.json を symlink にしない。安全のため、symlink・他のユーザーの所有の状態ディレクトリには書き込まず、symlink の metadata.json は読まない（名前・区分が一覧に出ず、保存はエラーになる。docs/STATE-FILES.md §1・§5）。

ドキュメント

開発

npm ci
npm run verify           # deps:check / lint / typecheck / テスト（カバレッジ 80%）/ build / knip
npm run watch            # 変更を監視してビルド（F5 で拡張開発ホストを起動）
npm run contracts:check  # 公式拡張の契約の検査
npm run secrets:scan     # 秘匿情報の走査

開発の規約は CLAUDE.md。

ライセンス

MIT