Agy Bridge

User → Claude Code → agy-bridge (MCP) → agy CLI → Gemini / Claude / GPT-OSS
                   ←                  ←          ←

claude-to-agy より優れている点

	claude-to-agy	agy-bridge
ツール構成	汎用的な delegate_to_agy が1つ	用途別に設計されたツールが6つ。Claude が確実に振り分けます
モデル選択	なし（agy のデフォルトのみ）	agy models の全モデルを対象にツールごとに振り分け、利用可否の検出とフォールバックに対応
マルチターン	ステートレス	セッションを継続し、follow_up でコンテキストを再送せずに agy の会話を再開できます
出力の安全性	上限なし	設定可能な切り詰め上限で Claude のコンテキストを保護します
サンドボックス	なし	オプションで --sandbox モードを利用できます
インストール	uvx（Python）	npx（Node）。インストール不要

必要要件

• Node.js 18+
• インストールして認証済みの Antigravity CLI（agy）
• Claude Code

インストール

# 1. Register the MCP server (user scope = all projects).
#    add-json bakes in a generous client-side timeout so long analyze_files /
#    delegate calls don't trip Claude Code's tool-call deadline (see Timeouts).
claude mcp add-json -s user agy-bridge \
  '{"command":"npx","args":["-y","agy-bridge"],"timeout":600000}'

# 2. Add delegation rules to your project (or ~/.claude/CLAUDE.md for global)
curl -o CLAUDE.md https://raw.githubusercontent.com/sshahzaiib/agy-bridge/main/CLAUDE.md

"timeout": 600000（10分、ミリ秒単位）は、クライアント側のツール呼び出し期限です。これを設定しないと、コールドスタート時の analyze_files（約40～50秒）や長時間の delegate が Claude Code のデフォルト期限に達し、agy の実行が続いているにもかかわらず timed out waiting for response が返ることがあります。クライアントがサーバーごとの timeout に対応していない場合は、代わりにグローバル環境変数 MCP_TOOL_TIMEOUT=600000 を設定してください。 詳細と agy 側のタイムアウト設定については、タイムアウトとキャンセルを参照してください。

ツール

ツール	用途	モデルのルーティング（最初に利用可能なもの）
analyze_files	200 行を超えるファイル、一度に 3 ファイルを超えるファイル、ログ、ダンプ、生成されたコード	Gemini 3.5 Flash (High) → Gemini 3.1 Pro (Low)
deep_search	git log/diff/blame の調査、リポジトリ全体の grep	Gemini 3.5 Flash (Medium) → (High)
web_lookup	ドキュメント、API リファレンス、外部および最新の知識	Gemini 3.5 Flash (Medium) → (High)
adversarial_review	計画の批評、設計およびコードのレビュー	Gemini 3.1 Pro (High) → Claude Opus 4.6 (Thinking) → Flash (High)
follow_up	session_id を使って以前のセッションを続行 — コンテキストの再送信は不要	セッションを継承
delegate	その他の負荷の高い作業	Gemini 3.5 Flash (High)

すべてのツールで、オプションの cwd（プロジェクトルート）と model（agy models に表示される ID または表示名）を指定できます。モデル名は検証され、一致しない場合は利用可能なモデルが一覧表示されます。

すべての応答は、次のフッターで終わります。

---
[agy-bridge] model: Gemini 3.5 Flash (High) | session: 1f0c…-d4 (use follow_up to continue)

モデルのルーティング

ブリッジは初回使用時に agy models を実行し（プロセスの存続期間中キャッシュされます）、ツールの優先モデルチェーンから最初に利用可能なモデルを選択します。利用可能なモデルがない場合は、AGY_DEFAULT_MODEL にフォールバックし、最後に agy 独自のデフォルトを使用します。agy は不明な --model 値を黙って無視するため、リクエストが誤ったモデルに送られないよう、ブリッジは事前にモデル名を検証します。

クォータを考慮したフェイルオーバー

agy はプリントモードではクォータ超過を通知しません。プリントタイムアウトに達するまで 429 を黙って再試行し、その後、空の出力を伴って終了コード 0 で終了します。そのため、以前は処理が無期限に停止したように見えていました。ブリッジは各実行のログファイル（--log-file 経由）を監視し、RESOURCE_EXHAUSTED (code 429) が発生すると、次の処理を行います。

1. タイムアウトまで待つことなく、agy プロセスグループを直ちに終了します。
2. リセット時刻（「4h24m 後にリセット」）を解析し、プロセス内のクールダウンレジストリに記録します。
3. 同じプロンプトを、ツールのチェーン内にある次のモデルで再試行します。
4. クォータがリセットされるまで、以降のすべての呼び出しでクールダウン中のモデルをスキップします。

フェイルオーバーは応答フッターに注記されます（failover: <model>: quota exhausted (resets in 4h24m)）。すべての候補モデルが使い果たされた場合に限り、呼び出しは停止せず、リセット時刻を一覧表示して数秒で失敗します。

タイムアウトとキャンセル

各ツールには用途に応じたデフォルトのタイムアウトが設定されています。web_lookup は 120s、deep_search は 180s、analyze_files／adversarial_review／follow_up は 300s、delegate は 600s です。AGY_TIMEOUT を明示的に設定すると、すべてのツールのタイムアウトが一度に上書きされます。個別のツールを変更するには、代わりに AGY_TIMEOUT_<TOOL_NAME> を設定します（例：AGY_TIMEOUT_DEEP_SEARCH=300）。ツールごとの設定は、グローバルな AGY_TIMEOUT とツールのデフォルトより優先されます。ツールごとの環境変数は、AGY_TIMEOUT_ANALYZE_FILES、AGY_TIMEOUT_DEEP_SEARCH、AGY_TIMEOUT_WEB_LOOKUP、AGY_TIMEOUT_ADVERSARIAL_REVIEW、AGY_TIMEOUT_FOLLOW_UP、AGY_TIMEOUT_DELEGATE です。終了処理では、プロセスグループ全体に対して SIGTERM から SIGKILL へ段階的に強制終了し、agy のヘルパープロセスが出力パイプを開いたままにしていても、期限に達するとタイムアウトします。MCP クライアントからツール呼び出しをキャンセルした場合（例：Claude Code で Esc キーを押す）、孤立させずに agy の実行も終了します。

2 つのタイムアウト層 — 互いに合わせてください。 上記のタイムアウトは、_agy 側_の実行時間の上限です。MCP クライアント（Claude Code）にも独自の、別個の_ツール呼び出し_タイムアウトがあります。これが agy の実行時間の上限より短いと、先にクライアントが待機を諦め、Error: timed out waiting for response が表示されます（注：agy-bridge 自体のタイムアウトは、代わりに agy timed out after Ns と表示されます）。作業が失われるわけではありません。agy のセッションは保持されるため、返された session_id を指定して follow_up を実行すれば結果を取得できます。ただし、根本的な解決策は、クライアントが agy と同じ時間以上待機するようにすることです。Install コマンドでは、すでにサーバーごとの timeout が 600000ms に設定されています（agy-bridge の項目だけが対象です）。この設定なしでサーバーを登録した場合は、Install の add-json コマンドを再実行するか、グローバル環境変数 MCP_TOOL_TIMEOUT=600000 を設定してください。目安：クライアントの timeout ≥ agy の実行時間の上限。

想定される応答時間。 体感上の「遅さ」の大半はコールドスタートによるものです。セッション内で最初に呼び出すと、agy CLI が起動し、モデルがウォームアップされます。3 ファイルに対する単純な analyze_files は、コールドスタート時に約 40–50s（実測値は約 46s）かかり、同じセッション内での以降の呼び出しでは短くなります。最初の呼び出しでクォータの 429 にも遭遇すると、ブリッジがフェイルオーバーするため、さらに時間がかかります。そのため、クライアントのタイムアウトが約 60s 未満だと、「単純な」質問でもコールドスタート時に断続的にタイムアウトします。余裕を持って設定してください。

設定

すべて任意で、環境変数を使用して設定します。

変数	デフォルト	説明
AGY_PATH	agy	agy バイナリへのパス
AGY_TIMEOUT	ツールごと	秒単位。ツールごとのタイムアウトをすべて一度に上書きします（上記を参照）。--print-timeout として渡され、15s の強制終了猶予を設けて適用されます
AGY_TIMEOUT_<TOOL>	ツールごと	秒単位。単一のツールのタイムアウトのみを上書きします。例：AGY_TIMEOUT_DEEP_SEARCH=300。AGY_TIMEOUT より優先されます
AGY_MAX_OUTPUT_CHARS	50000	ツール出力の切り詰め上限
AGY_DEFAULT_MODEL	未設定	チェーン内にエントリーがない場合のフォールバックモデル
AGY_SKIP_PERMISSIONS	true	agy に --dangerously-skip-permissions を渡します
AGY_SANDBOX	false	--sandbox を付けて agy を実行します
AGY_ON_FAILURE	fallback	strict にすると、ツール失敗時のエラーに、呼び出し元のエージェント自身で作業を引き取らないよう指示する文が追加されます

失敗時の動作

ブリッジは常に失敗を明確に通知します。agy のエラーは、agy の実際の stderr とともに MCP ツールエラーとして表示され、モデルルーティングの性能が低下した場合は、レスポンスのフッターに注記されます。デフォルトでは、失敗後に呼び出し元のエージェント（Claude）が通常、自分で作業を行います。これはトランスクリプトで確認できますが、長いセッションでは気付きにくくなります。AGY_ON_FAILURE=strict を設定すると、すべての委任エラーに「この作業を自分で行ってはいけません。失敗をユーザーに報告してください」という明示的な指示が追加され、トークン節約がひそかに失われるタイミングを自分で制御できます。

開発

npm install
npm test           # vitest unit tests (exec mocked — no agy needed)
npm run typecheck
npm run build      # tsup → dist/index.js

コントリビューター

コントリビューションを歓迎します。Issue または PR を作成してください。

Star History

ライセンス

MIT