Codex Agy Bridge

codex-agy-bridge

エージェントハーネスから Antigravity を実行し、MCP 経由で永続的かつ並列で、人が操作できる agy セッションを利用できます。

codex-agy-bridge は、公式 Antigravity CLI を再開可能な MCP 制御プレーンでラップします。 Codex、Claude Desktop、または独自の GPT／Claude 搭載 MCP クライアントなどのエージェントハーネスから、 agy の実行を開始し、間隔の空いたイベントを待ち、実際のターミナルに接続し、制限付きで入力を送信し、 安全にキャンセルし、会話を正確に継続して、後から run_id で最終結果を収集できます。

クイックインストール

前提条件：

• 以下のコマンドを実行するための Codex CLI、または別のローカル stdio 対応 MCP ハーネス
• 公式 Antigravity CLI（agy）。ローカルで認証済みであること
• uv／uvx
• tmux とサポート対象のターミナルランチャー：

# macOS
brew install tmux

# Debian/Ubuntu Linux (x-terminal-emulator is also supported)
sudo apt install tmux gnome-terminal

必要なコマンドを確認します：

codex --version
agy --version
agy models
uvx --version
tmux -V

初日の認証

agy --version で確認できるのは、バイナリが存在することだけです。MCP サーバーを追加する前に、 agy models を実行してください。Antigravity からサインインを求められるか、ログインしていないと 表示された場合は、表示可能なセッションを開始し、ブラウザー／ログインの手順を完了してください：

agy --prompt-interactive "Authenticate Antigravity and then exit."
agy models

agy models が成功したら、MCP サーバーをインストールするか、再起動してください。ブリッジの実行時に 認証エラーが発生した場合、agy_run_start は status="auth_required" を返し、デフォルトで 表示可能な agy 認証セッションを開きます。そこでサインインを完了してから、新しい実行を開始してください。 agy_run_observe(view="terminal") または agy_admin(action="doctor") を使って、認証が必要な状態を 確認することもできます。

Codex CLI を使って PyPI からインストールします：

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

ハーネスを再起動し、上記のコマンドを使った場合は Codex で確認します：

codex mcp get codex-agy-bridge
codex mcp list

次のコマンドで削除できます：

codex mcp remove codex-agy-bridge

Claude Desktop またはカスタム MCP クライアントでは、同じ stdio コマンド形式を使用してください： AGY_CMD に認証済みの agy 実行ファイルを設定したうえで、uvx codex-agy-bridge@latest を実行します。

何が違うのか

• Antigravity セッションの並列実行： 独立した agy 実行を複数起動できます。 それぞれが独自の永続状態、ログ、トランスクリプトの投影、結果を保持します。
• 人が操作できるターミナル： フォアグラウンド実行は永続的な tmux セッション内で行われるため、エージェントを終了させずに Terminal.app から接続できます。
• 再開可能な MCP 制御： MCP 呼び出しがタイムアウトしても、ハーネスが再起動しても、 後から run_id で実行を確認できます。
• 目標のオーケストレーション： 目標を作成し、並列数に上限を設けて名前付きターゲットを開始し、 バッチ全体を連携した作業として確認できます。
• 疎な起床イベント： agy_run_wait は、トランスクリプトをポーリングし続けることなく、 ライフサイクル、注意、進捗、終了の各イベントを短い間隔でポーリングします。
• 制限付き入力： 呼び出し側が実行を確認した後でイベントまたはトランスクリプトのカーソルが 変化していた場合、agy_run_input は古い書き込みを拒否できます。
• 軌跡を考慮した可観測性： モデルの非公開の推論を公開せず、上限付きのトランスクリプト要約と ターミナルの証跡を提供します。
• 運用上の衛生管理： 重複したアクティブな実行の開始は重複排除され、プロセスグループは安全に キャンセルされ、完了した結果の成果物は保持されます。

インストールの詳細

これを読んでいるエージェントの方へ

ユーザーのインストールを支援してください。ユーザーに知らせずにマシンを変更してはいけません。

1. まず前提条件を確認します：

command -v codex
command -v agy
command -v uvx
command -v tmux
agy --version
agy models

2. 不足しているものがあれば、インストールする前にユーザーに確認してください。
3. agy models で認証エラーが報告された場合は、MCP サーバーを追加する前に、 上記の初日の認証手順を完了できるようユーザーを支援してください。
4. 次に、以下を実行します：

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- "$(command -v uvx)" codex-agy-bridge@latest

5. 確認します：

codex mcp get codex-agy-bridge
codex mcp list

6. 新しい MCP ツールを読み込むため、エージェントハーネスを再起動するようユーザーに伝えてください。

PyPI

Quick Install コマンドは、stdio MCP サーバーの定義を保存します。エージェントハーネスがサーバーを起動すると、uvx は PyPI から codex-agy-bridge@latest を解決し、分離されたキャッシュ環境にインストールして、codex-agy-bridge コンソールスクリプトを実行します。AGY_CMD は、ブリッジがユーザーのインストール済みで認証済みの agy 実行ファイルを使うよう固定します。

コマンド内の $ や $(...) を手動で置き換えないでください。POSIX シェルでは、$(command -v agy) と $(command -v uvx) は絶対パスの実行ファイルに展開されます。

GitHub

リポジトリのバージョンを直接使う場合は、こちらを使用してください。

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uvx --from git+https://github.com/varadfromeast/codex-agy-bridge \
  codex-agy-bridge

ローカル開発

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev

codex mcp add codex-agy-bridge \
  --env AGY_CMD="$(command -v agy)" \
  -- uv --directory "$PWD" run codex-agy-bridge

仕組み

flowchart LR
  H["Agent harness<br/>(Codex, Claude, custom MCP client)"]
  M["codex-agy-bridge<br/>MCP stdio server"]
  S["Durable control plane<br/>runs, goals, events, results"]
  W["Detached run supervisor"]
  A["Antigravity CLI<br/>agy"]
  T["Persistent tmux session<br/>human attach/input"]
  L["Local Antigravity<br/>trajectory files"]

  H <-->|"MCP tools"| M
  M <--> S
  S --> W
  W --> A
  W <--> T
  A --> L
  W -->|"bounded transcript projection"| S
  T -->|"terminal logs and attention prompts"| S

ブリッジは、デタッチされたスーパーバイザーが長時間実行される agy プロセスを管理する間も、MCP サーバーの応答性を維持します。状態とイベントはローカルに保存されるため、元の MCP 呼び出しが返された後も実行を継続できます。プロセスモデルの詳細については、docs/ARCHITECTURE.md を参照してください。MCP 制御ループのビジョンについては、docs/MCP_VISION.md を参照してください。

MCP ツール

ツール	目的
agy_run_start	対話型のフォアグラウンド実行を開始、継続、または開きます
agy_run_wait	選択した実行が簡潔なウェイクイベントを発するまで短時間ポーリングします
agy_run_observe	全体、ステータス、トランスクリプト、または生のターミナル表示を読み取ります
agy_run_input	任意のイベント／トランスクリプトの事前条件を指定して入力を送信します
agy_run_cancel	アクティブな実行を 1 つキャンセルします
agy_run_result	最終結果のメタデータまたは上限付きの結果チャンクを読み取ります
agy_goal	ゴールを作成し、ターゲットを開始して、集約ステータスを読み取ります
agy_admin	診断情報、モデル、プラグイン、検証結果、変更履歴を読み取ります

model を省略する（または null を渡す）と、Agy がデフォルトを選択します。ブリッジは model: null を保存し、--model は送信しません。これは実行、レビュー用ツール、およびゴールに適用されます。ゴールのターゲットは、そのゴールの選択を引き継ぎます。明示的な選択は、ブリッジの以前のデフォルトである Gemini 3.5 Flash (Medium) を含め、agy models に照らして検証されます。不明な選択や空の選択は拒否されます。ブリッジがカタログの先頭項目を代わりに選択することはありません。agy_admin(action="models") は default_model: null と default_model_source: "agy_cli" を報告します。これは選択を委任していることを示すもので、実際に使用されたプロバイダーモデルを観測した結果ではありません。

既存の保存済み実行とゴールはモデル文字列を保持し、引き続き読み取り可能です。別のモデルに暗黙に移行されることはありません。古いゴールから新たに起動する場合、その選択が再検証され、利用できなくなっていれば拒否されます。利用可能なモデルで新しいゴールを作成するか、選択を省略して Agy に委任してください。以前に予約された実行は、元のコマンドポリシーを保持します。新たに委任されるリクエストには、明示的にモデルを選択した場合とは異なる重複排除キーが割り当てられます。ゴールのモデルに文字列を必須とする古いブリッジバージョンでは、新しい null モデルのゴールを読み取れません。そのようなゴールを使用中の場合は、ダウングレードしないでください。

一般的なフロー：

agy_run_start -> agy_run_wait -> agy_run_observe -> agy_run_result

Codex MCP では、たとえば codex_agy_bridge_agy_run_wait のように、サーバーのプレフィックス付きでツールが公開されることがあります。実行レスポンスには正確な wait_call 引数が含まれます。agy_run_wait は、実行が 1 つだけの場合でも、常に run_ids: ["..."] を受け取る点に注意してください。サポートされている待機条件は、any_attention、any_terminal、all_terminal、any_event と、エイリアスの attention、terminal、finished、finish、complete、completed、result、all_finished、all_complete、all_completed です。

ハーネスで、共有の目標と上限付きの並列処理を持つ名前付きターゲットに作業を分割する場合は、agy_goal を使用してください。

設定

変数	デフォルト	用途
AGY_CMD	agy on PATH	Antigravity の実行ファイルを指定します
AGY_BRIDGE_STATE_DIR	~/.local/state/codex-agy-bridge	実行状態と目標状態を永続化します
AGY_BRIDGE_AGY_ROOT	~/.gemini/antigravity-cli	Antigravity の会話と軌跡
AGY_BRIDGE_MAX_PARALLEL	50	グローバルな同時実行数の上限
AGY_BRIDGE_COMPLETION_STABILITY_SECONDS	150	最終マーカーが安定した状態を維持する必要がある時間
AGY_BRIDGE_MCP_WAIT_SLICE_SECONDS	120	1 回の agy_run_wait MCP 呼び出しがスナップショットを返すまでにブロックする最大秒数。ゲートウェイのタイムアウトを防ぎます

実行状態は、MCP サーバーを再起動しても ~/.local/state/codex-agy-bridge/ に保持されます。

ステータスとリスク

このプロジェクトは実験段階です。現在は Python 3.11 以降、サポートされているターミナルランチャーと tmux を備えた macOS または Linux、および Antigravity CLI 1.0.8 と互換性のあるコマンドと軌跡ファイルを対象としています。

Antigravity はエージェント型の CLI です。現在のユーザーの権限でファイルの読み書き、コマンドの実行、 ネットワークへのアクセスが可能です。このブリッジはサンドボックスでもセキュリティ境界でもありません。

ブリッジは、無人実行が CLI の承認プロンプトで停止しないよう、常に Antigravity の危険な権限スキップポリシーを有効にします。 dangerously_skip_permissions=false を指定した入力は拒否され、許可される値は true のみです。sandbox=true と additional_directories は CLI のポリシーヒントであり、ファイルシステムの隔離を行うものではありません。

ブリッジは Antigravity の OAuth 認証情報を読み取ったりコピーしたりしません。インストール済みの agy バイナリを実行し、通常のローカル会話メタデータと軌跡ファイルを読み取ります。

開発

git clone https://github.com/varadfromeast/codex-agy-bridge.git
cd codex-agy-bridge
uv sync --extra dev
uv run pytest
uv run ruff check .
uv build

サーバーを直接実行します。

uv run codex-agy-bridge

サーバーは stdio トランスポートを使用します。診断テキストを stdout に出力しないでください。MCP のフレーミングが壊れます。

公開

バージョンタグをプッシュすると .github/workflows/publish.yml が実行され、バージョンを検証し、チェックを実行し、配布物をビルドして、 GitHub OIDC 経由で PyPI に公開し、GitHub リリースを作成して、server.json を MCP Registry に公開します。

互換性

現在のリーダーは、次の場所にある Antigravity の軌跡 JSONL を想定しています。

~/.gemini/antigravity-cli/brain/<conversation-id>/
  .system_generated/logs/transcript.jsonl

Antigravity が SQLite またはローカルデーモン API に移行した場合、新しいアダプターでこのリーダーを置き換えても、MCP ツールの契約を変更する必要はありません。

ライセンス

MIT