目的と背景（Why）
- 目的は「CLIエージェント（Codex）から、ユーザーが普段使っている“ログイン済み”Chromeを確実に操作する」こと。
- 既存の自動化（Playwright等）は“ログイン済みプロファイルをそのまま操作”が難しく、特にGoogle系サービスで弾かれやすい。ユーザーが普段操作しているChromeを直接扱う必要がある。
- Claude in Chromeの本質的問題は「稼働状態が観測できない」「突然切れる」「復旧導線がない」。本プロジェクトはここを設計で潰す。
- ツール分裂は避けたい。Codexが“いつもの使い方”で安定して呼べる単一のCLI（＋背後のブリッジ）を提供する。
スコープ（What）
- 提供物
-
ローカル常駐ブリッジ（daemon）
- Chrome拡張と常時接続し、ブラウザ操作リクエストを中継する
- CLIを提供し、CodexはこのCLIだけを使えばよい
-
Chrome拡張
- 対象タブに対し、Chrome Debugger API（Chrome DevTools Protocol相当のコマンド送信）で操作を実行する
- 接続状態・切断理由・復旧操作をUIで提示できる
-
CLI（Codexが叩く唯一の入口）
- “snapshot → ref → action” の決定論的な操作モデルを提供する
- テキスト出力（LLMに読みやすい）とJSON出力（機械処理しやすい）を両方提供する
- 必須ユースケース（最低限）
- タブ選択（現在アクティブ／指定タブ）
- snapshot取得（refs付きの要約）
- click / fill / keypress / scroll / navigate の最小セット
- 失敗時に「何が起きたか」を返す（切断理由・タイムアウト・要素不一致など）
- 非目標（やらない）
- サイト固有の自動化ロジックを大量に持つ（汎用操作で足りる範囲に留める）
- “完全自動でChromeを起こす”の保証（接続が無いときはキュー／手動復旧へ）
- Playwright互換の完全実装（必要な操作だけ）
Codex向け：インターフェース設計方針（What）
-
操作モデルは agent-browser 風に寄せる（重要）
- 返すsnapshotは「短い」「決定論的」「refsで再指定できる」
- 例：
button "ログイン" [ref=e12]のように、以後はclick e12で操作できる
-
refは「snapshot内でのみ有効」にする（安定性のため）
- どのsnapshotから生成されたrefか（snapshot_id）を必ず返す
- アクションは原則「最新snapshot_id」に対して実行し、ズレたら再snapshotを要求する
-
エラーは“原因究明優先”の構造化（最重要）
- 例：
DISCONNECTED(reason=…)/TIMEOUT(phase=…)/NO_SUCH_REF/STALE_SNAPSHOTなど - “復旧指示”を返す（例：
reconnect_required,reset_session_recommended）
- 例：
信頼性・復旧（Why → What）
-
目的：突然切れても「自動で戻る」か「手動で確実に戻せる」状態にする
-
実装要件（What）
-
自動再接続（指数バックオフ、ハートビート、再同期）
-
切断検知と理由の伝播（拡張→daemon→CLI→Codexログ）
-
復旧コマンド（最低2つ）
- reconnect（通信再確立）
- reset（操作セッション破棄→再アタッチ→キャッシュ破棄）
-
キュー（拡張不在時の扱い）
- “失敗で即終了”ではなく、一定時間は保留→復帰後に実行、または明示的に失敗を返す（選べる）
-
観測可能性（Why → What）
-
目的：ユーザーが「今どの状態か」「なぜ失敗したか」を一目で把握できること
-
実装要件（What）
-
拡張UIに状態表示
- daemon接続（connected/disconnected、最終ping、再試行回数）
- 操作対象タブ（tab_id、アタッチ中か）
- 最後のエラー（切断理由含む）
-
CLIに診断出力モード
- 直近N件のイベント、切断履歴、再接続履歴をワンコマンドで出せる
-
セキュリティ（What）
- ローカル専用（127.0.0.1 bind）
- 認可：拡張↔daemon間に共有トークン（最低限）を持たせ、任意ローカルプロセスからの操作を抑止
- ログやsnapshotに機密が含まれ得る前提で、保存の有無を明確化（デフォルトは保存しない、必要時のみ明示的にdump）
How（メタ方針：実装を軽くするための進め方）
-
“AXTree周りをゼロから再発明しない”
- 目標は「refs付きsnapshot」と「ref→操作」の最小閉路
- snapshot圧縮・refs表現など、既に筋が良いものは流用する
-
vendor方針（推奨）
- agent-browserの「出力フォーマット」「refs付与」「スナップショット要約」部分は、依存としてimportするより“vendor（特定コミット固定で取り込み）”を優先
- 理由：外部の公開APIが安定していない場合、importは破壊的変更の影響を受ける。vendorなら再現性が上がる
- vendorする範囲は「純粋ロジック（文字列生成・ツリー圧縮・ref採番）」に限定し、ブラウザI/Oは自前の境界面に隔離する
-
テスト方針（推奨）
- ユニットテスト：snapshot→refs生成が決定論的であること（同入力なら同出力）
- 変換テスト：ref辞書の整合性（refが指す対象が変わったら検知できる）
- 統合テスト：ローカルの固定HTML（自前テストページ）で click/fill の最小往復を自動化
- 回帰テスト（手動でも良い）：ログイン必須の代表ケース（Google系など）は「壊れやすいので“短い手順”で毎回同じ検証ができる」チェックリストを用意
-
段階的リリース
- まずは「観測可能性＋最小操作」の完成を優先（ここがClaude in Chromeとの差分）
- 次に「自動再接続・再同期」を固める
- 最後に操作コマンド拡張（wait系・network観測など）を足す
Codexへの作業指示（実行順のWhat）
- CLIの仕様を確定（コマンド名、入出力、エラー体系、診断モード）
- daemon↔拡張のプロトコルを最小で定義（request_id、snapshot_id、タブ指定、エラー）
- “snapshot→ref→click” の最短経路を実装し、ローカル固定HTMLでテストを通す
- 切断理由の可視化（拡張UI＋CLI診断）を先に入れる
- 自動再接続＋reset/reconnectを実装
- vendor取り込み（ref表現・圧縮ロジック）を固定コミットで行い、出力安定性テストを追加
質問があればどうぞ。