Antigravity ベストプラクティス
Google の Antigravity 2.0(デスクトップアプリ)と Antigravity CLI(agy)について、設定ファイル、ルール、カスタムエージェント、Hooks、権限とサンドボックスの使い方を整理しています。
2026-11-02 に照合済み(CLI は google-antigravity/antigravity-cli の README・CHANGELOG、機能説明は antigravity.google/docs の要約。antigravity.google には直接接続できなかったため一部要確認)
最新アップデート
ニュースに収録済みの直近3件です。全件はニュースから確認できます。
2026-11-05Antigravity CLI v1.5.0〜v1.5.1 — stdio ACP サーバー agy acp と --remote-agent を追加
agy acp で ACP クライアントから Antigravity CLI を使えるように(session/resume・ターン中の steer・agy acp --login)。--remote-agent で会話をリモートエージェント上で実行。挙動変更: ヘッドレスの -p はバックグラウンドタスクを既定で待ち、--print-timeout で打ち切られると終了コード 3。
セキュリティ: プラグインの OAuth トークンを Authorization ヘッダーの中でだけ置換し、サイトが実トークンをエコーバックできないように(v1.5.1)。ニュースを読む
2026-10-30Antigravity CLI v1.4.8〜v1.4.12 — PreInvocation hook でモデルの呼び出し前にターンを止められるように
PreInvocation hook が terminationBehavior: "terminate" でモデルを呼ぶ前にターンを止められるように。errorMessage.userMessage で、モデルには送らずユーザーにだけメッセージを表示できます(-p 実行では終了コードが 0 以外に)。画像の貼り付け・ドラッグ&ドロップに対応(SSH 越しは X11 か Wayland の転送が有効なとき)。
セキュリティ: Google サイトへの承認が、機密性の高い Google アプリにまで及ばないように。ニュースを読む
2026-10-24Antigravity CLI v1.4.7 — hook の入力に lastUserInput、プラグイン MCP の OAuth トークンの不具合を修正
hook が標準入力で受け取る JSON に最新のユーザーメッセージ lastUserInput が加わり、エージェントが動く前にプロンプトを検査できるように。
セキュリティ: OAuth でサインインするプラグインの MCP サーバーが、同じ OS アカウントの別ユーザーのトークンを使えた不具合を修正。ニュースを読む
概要とベストプラクティス
antigravity.toml での設定」「Jules・IDX と連携する3アプリ構成」「Gemini 2.5 Pro の 2M トークン」などを載せていましたが、移行期限はすでに過ぎており、そのほかは公式の情報で確認できませんでした。確認できた内容に書き直しています。概要
- Google 製。GUI のデスクトップアプリ Antigravity 2.0 と、ターミナルで動く Antigravity CLI(
agy)がある - 2つは同じエージェントエンジンを使い、設定と権限は双方向に同期される。CLI のセッションを 2.0 に書き出して続きを作業できる
- ルールは
AGENTS.mdとGEMINI.md。Skills・カスタムエージェント・Hooks・プラグイン・MCP で拡張できる - 権限は確認方式とサンドボックスで管理。Auto mode では安全な操作は確認なしで進む
- Remote Control でブラウザからセッションを操作できる
ベストプラクティス 8
- プロジェクトの指示は
AGENTS.mdに書く(他のツールとも共有できる) - 繰り返す手順は Skill(
.agents/skills/<name>/SKILL.md)に切り出す - 危険なコマンドの拒否や機密情報の検査は、指示文ではなく Hooks(PreToolUse・PreInvocation)で行う
- ターミナルのサンドボックスを有効にし、外に出るコマンドは確認させる
- 信頼していないリポジトリは、ワークスペースを信頼する前に
.agents/hooks.jsonなどの中身を確認する(ワークスペースの hooks は信頼した後に読み込まれる) - プラグインは中身(MCP サーバー・hooks)を確認してから入れる
--dangerously-skip-permissionsは使い捨ての環境だけで使う- AI エージェントにはコードの自動実行・データの持ち出し・プロンプトインジェクションなどの危険がある前提で、操作を確認する(README の警告)
CLI のインストールと起動
01インストール・ログイン
# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Windows PowerShell
irm https://antigravity.google/cli/install.ps1 | iex
# Windows CMD
curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd
# 起動
agy
- 認証はシステムのキーリングを使い、セッションがなければ Google でサインインします。SSH 越しでは認可用の URL が表示されます。
/logoutでサインアウト GEMINI_API_KEYを設定し、settings.jsonでmodelProvider: "gemini"にすると、サインインせずに Gemini API で動かせます- 企業で使う場合は、オンボーディングで GCP プロジェクトを接続します
インストールスクリプトを直接シェルに渡す方法は公式の手順ですが、実行前にスクリプトの中身を確認すると安全です。
02よく使うフラグとコマンド
| コマンド・フラグ | 内容 |
|---|---|
-p / --print | 非対話で1回実行(--output-format json / stream-json で構造化出力) |
--model / /model、--effort / /effort | モデルと推論の深さを選ぶ |
--mode | 実行モード(default・accept-edits・plan・auto)。Shift+Tab や /config でも切り替え |
--agent / /agents | カスタムエージェントを選ぶ・一覧する |
/compact | 会話を要約してコンテキストを空ける |
/hooks | 読み込まれている Hook を確認 |
/plugin | 公式マーケットプレイスからプラグインを探す・入れる |
/resume | 過去の会話を再開 |
/remote-control | ブラウザからの操作を有効にする |
設定ファイルの場所
01全体・プロジェクトの設定
~/.gemini/antigravity-cli/settings.json # CLI の設定(権限・モード・モデルなど)
~/.gemini/config/ # 2.0 と共有する全体の設定
AGENTS.md GEMINI.md rules/ # 全体のルール
hooks.json # 全体の Hook
agents/ # 全体のカスタムエージェント
plugins/ plugins.json skills.json rules.json agents.json mcp_config.json
config.json # 共有設定(プラグインの有効・無効など)
projects/ # プロジェクトごとの権限
<プロジェクト>/.agents/
hooks.json # プロジェクトの Hook
agents/ # プロジェクトのカスタムエージェント
skills/<name>/SKILL.md # プロジェクトの Skills
- プロジェクトごとの権限(
~/.gemini/config/projects/)は、全体の設定より優先されます .agents/の skills.json・rules.json などは、作業ディレクトリからプロジェクトのルートまでの各階層のものが読み込まれます- エージェントに読ませたくないファイルは
.antigravityignoreに書けます
ルールとカスタムエージェント
01ルール(AGENTS.md・GEMINI.md)
- プロジェクトの
AGENTS.mdと、全体の~/.gemini/AGENTS.md・~/.gemini/GEMINI.md(または~/.gemini/config/内の同名ファイル)が読み込まれます - これらのルールは、組み込みの指示より優先されるように扱われます
02Markdown のカスタムエージェント
# .agents/agents/reviewer/agent.md
---
name: reviewer
description: Reviews diffs for security issues
model: inherit # サブエージェントとして動くときのモデル(flash / pro など)
subagent: true
---
# Reviewer
You review code changes and report security issues only.
- YAML フロントマターと、H1 見出しで始まるシステムプロンプトで書きます
- フロントマターで
skills・rules・agents・plugins・hooksを指定できます(エージェントのファイルからの相対パスも可) - 既定では、全体の Skills・ルール・サブエージェントを引き継ぎます(引き継ぐかどうかは
inheritCustomizationsで指定)。excludeDefaultComponents: trueは、既定のプロンプトの一部と組み込みツールを外す設定です(post-invocation の hooks は残る) subagent: falseにするとサブエージェントとしては呼ばれません
Hooks
決まった時点でコマンドを実行する仕組みです。入力は標準入力の JSON で受け取り、結果を標準出力の JSON で返します。
01イベントと置き場所
| イベント | タイミング |
|---|---|
PreToolUse / PostToolUse | ツールの実行前 / 後(matcher でツールを指定) |
PreInvocation | モデルを呼ぶ前。terminationBehavior: "terminate" でターンを止められる |
PostInvocation | モデルの呼び出しが終わった直後 |
Stop | ターンの終了時 |
- matcher が使われるのは
PreToolUse・PostToolUseだけで、PreInvocation・PostInvocation・Stopでは無視されます - 置き場所: プロジェクトは
.agents/hooks.json、全体は~/.gemini/config/hooks.json、プラグインに含まれる hooks.json - hook の入力 JSON には、最新のユーザーメッセージ
lastUserInputも含まれます(v1.4.7 から) - CLI で使えるイベントの正確な一覧(SessionStart など)は、公式ドキュメントの Hooks ページで確認してください
出典: Hooks(CLI) · CHANGELOG
権限とサンドボックス
01実行モード
| モード | 動き |
|---|---|
default | 確認しながら進める |
accept-edits | ファイルの編集は確認なしで進める |
plan | 計画を立てる |
auto | ファイルの編集と安全なコマンドは確認なし、取り返しのつかない操作は確認する。サンドボックスの外に出るコマンドは別のエージェントが確認する。Windows では Windows 11 24H2 以降・個人の Google アカウントで使える |
確認の画面で「常に許可」を選ぶと、許可ルールとして保存されます(settings.json の permission.allow が参照されるほか、Remote Control から承認したルールは共有の ~/.gemini/config/config.json に保存されるなど、保存先は経路によって異なります)。ヘッドレス(-p)の実行でも、保存した権限・サンドボックス・自動実行の設定が使われます。
02ターミナルのサンドボックス
- エージェントが実行するコマンドを、ファイルやネットワークへのアクセスを制限した環境で動かします
- 既定で
~/.docker・~/.kube・~/_netrc(v1.4.6 から)や、macOS の~/Library/Application Supportにはアクセスできません - Windows は Windows 11 24H2 以降で使えます(管理者権限は不要)。Linux で非特権ユーザー名前空間が使えない環境では使えません
プラグイン
01プラグインの管理
/pluginで公式マーケットプレイスのプラグイン(Skills・MCP サーバー・サブエージェント・ルール・hooks をまとめたもの)を探して入れます- 設定が必要な MCP サーバーを含むプラグインは、設定するまで無効の状態で入ります。
Configure MCP servers...で後から変更できます - 自作のプラグインは
agy plugin validateでplugin.json・hooks.json・Skills などの書き方を確認できます
更新ログ
run_workflowツールを全員に開放、管理設定pluginControls。HTTP MCPのカスタムヘッダーがリダイレクト先の別ホストへ送られうる問題を修正。サンドボックス内コマンドが~/.config(WindowsはAppData\Roaming)と~/.git-credentialsを既定で読めなくなった⚠️。--remote-agentは既定モードでファイル編集ごとに確認。-p含む)はAuto modeで開始(/configでDefaultに戻せる)。hookのauto_approve/command(*)が管理者審査を回避していた問題、ネットワークプロキシのパスルール回避(%2F・..)、Windowsのalways-allow回避、eager MCPツールへの権限ルール未適用を修正🔒。Gemini 4 Hydrogen/Carbon追加。/swarm <task>(プレビュー・クォータ大量消費)。リモートのエンタープライズゲートウェイにhttps://必須化、プラグインインストールのアトミック化と危険なsymlink等の拒否。agy acpでAuto mode、hook入力にhookEventName/cwd/toolCall.id、Stop hookにcontinuation_active/agentsに各サブエージェントのモデルを表示、プラグインのhookコマンドにPLUGIN_ROOT・PLUGIN_DATAを渡すように。詳細はニュース参照。--dangerously-skip-permissionsでも組み込みの保護対象コマンドは通常の確認を経るように⚠️。ワークスペース外ファイルの承認は1パス単位に。agy pluginが危険なプラグイン名・フォルダ外/シンボリックリンク経由の書き込みを拒否し、.agents/plugins.json・.agents/skills.jsonはワークスペース/リポジトリルート内のみ読み込み。詳細はニュース参照。agy acpと--remote-agentを追加。ヘッドレス-pがバックグラウンドタスクを既定で待つように(--print-timeout超過で終了コード3)⚠️。プラグインOAuthトークンの置換をAuthorizationヘッダーに限定。詳細はニュース参照。PreInvocation hookがモデル呼び出し前にターンを停止しユーザーにだけエラー表示可能に。Googleサイトの承認が機密性の高いGoogleアプリに及ばないように、複数行always-allowルールが有効に。画像の貼り付け/ドラッグ&ドロップ、JSON出力のfinished_reason、Claude Codeプラグインのインポート改善。詳細はニュース参照。lastUserInputを追加(エージェント実行前のプロンプト検査が可能に)。OAuthでサインインするプラグインMCPサーバーが同じOSアカウントの別ユーザーのトークンを使えた不具合を修正(再サインインが必要な場合あり)。Auto modeが日常的なコマンドで承認を求める頻度を削減。オンデマンドMCPツールの結果を10KBまで直接返却~/.docker・~/.kube・~/_netrcへのアクセスを制限。権限承認がメイン会話とsubagentで一貫適用に。プラグインにConfigure MCP servers...行を追加。詳細はニュース参照。--mode auto・Shift+Tab、Linux/macOSのみ)と/compactを追加(v1.3.5)。agy plugin validateが実ロードと同じルールで検証し--strict/--json対応(v1.4.0〜)。ADCサインインでClaude Opus/Sonnet 5.5利用可能に(v1.3.6)。詳細はニュース参照。/plugin(agy plugin install <name>@antigravity-plugins-official)を追加。--dangerously-skip-permissionsが/planの実装計画を自動承認しなくなった(自動化は/configのArtifact Reviewで設定)。macOSサンドボックスが~/Library/Application Supportの読み取りを既定でブロック🔒。詳細はニュース参照。/diffファイルビューで←/→キーによるファイル間移動に対応、Windowsでプラグインインストール時にMCPサーバーを正しく停止するよう修正。詳細はニュース参照。--effortフラグを追加(v1.2.11)する一方、未設定プラグインが既定で無効状態から始まるよう変更(v1.2.11、⚠️挙動変化)。@<subagent>構文での直接メッセージング(v1.2.9)・関連ツール呼び出しをまとめるmedium verbosityモード(v1.2.10)・レート制限時にサーバー指定の待機時間へ対応(v1.2.13)を追加。詳細はニュース参照。--remote-controlフラグでセッション単位のターミナル共有機能「Remote Control」を追加。ヘッドレス実行のタイムアウトを既定の5分から無制限に延長。ヘッドレス実行のエラー報告を構造化されたAGY_ERROR形式のJSON出力に強化。詳細はニュース参照。/copy btwを追加(v1.2.3)。/skills reloadで再起動なしにスキルを非同期再読込・/modelの引数補完/ファジー検索を追加(v1.2.4)。invoke_subagentツールを持つカスタムエージェント向け自動サブエージェントガイダンスを追加(v1.2.5)。詳細はニュース参照。excludeDefaultComponents: trueを追加し、既定のプロンプトセクション・組み込みツールを除外しつつ呼び出し後フックは維持できるように。一時的なモデルAPIエラー(502/503/504・レート制限)を完了済みツール呼び出し結果を保持したまま指数バックオフで自動リトライ。ヘッドレス実行の失敗理由をerror:マーカー付きで明示。--continueが新規会話を開始してしまう不具合・インラインモードの全画面フラッシュ・Mermaid図の不要なズームコントロール表示を修正。詳細はニュース参照。remote-control start/status/stopサブコマンドでOSのサービスマネージャーに登録しログアウト・再起動をまたいで待受可能に(v1.2.0)。503等の一時的なモデルAPIエラーへのリトライを指数バックオフで強化。コンテンツセーフティフィルタでブロックされた際に明確な停止理由を表示するよう修正。詳細はニュース参照。/model <name> <prompt>を追加(v1.1.27)。指定モデルに単発プロンプトを投げて回答を得た後、元のモデルへセッションを自動的に戻す。アーティファクトビューアの半ページスクロール・会話リスト整理用pickerGrouping設定・Mermaidフローチャートのターミナル描画を改善(v1.1.26)。詳細はニュース参照。/resume会話ピッカーにCtrl+Fで切替可能なワークスペース別グループ表示を追加(v1.1.25)。モデルカタログにGEMINI_API_KEY接続向けGemini 3.8 Flashを追加。カスタムMarkdownエージェントがambientスキル・ルール・サブエージェントを既定で継承するように変更。/mcpパネルの矢印キー操作を改善、出力をパイプしたヘッドレスCLIの終了時ハングを修正(v1.1.24)。詳細はニュース参照。/model <name>の補完候補をTabキーで確定できるように改善。サブエージェントのストリーミングでtrajectoryメタデータをサブトラジェクトリごとに1回だけ送信しオーバーヘッドを削減。OAuthトークンを期限切れの5分前に事前更新し一時的な認証エラーを防止。Google Cloud認証中断時のチャットセッション破損・WindowsでBOM付きUTF-8のMCP設定JSONがパースできない不具合等を修正。詳細はニュース参照。/voiceを追加(v1.1.21、mic-serveでリモートマイク転送も可能)。スクリプトランナー(npm run等)へのallow-always提案が特定のスクリプト名にピン留めされるように変更(従来はnpm run dev承認で全スクリプトが許可されていた)。SKILL.mdのアイコン表示対応・/model <name>引数追加・アイドル時のCPU使用量を約32%→10%に削減。詳細はニュース参照。--projectフラグがプロジェクト名にも対応、対応音声フォーマットをwav/mp3/m4a/aac/flac/opusに拡大(v1.1.18)。詳細はニュース参照。/effortがGemini APIキー認証経由でGemini 3.6 Flash・3.7 Flashに対応。大規模ワークスペースの@ファイル補完をripgrep+キーストローク間引きで高速化。v1.1.17はエージェント実行経路統一のメンテナンスリリース(スラッシュコマンド消失・Vim insertモードEnterキー・Ogg音声/動画MIME判定の不具合を修正)。詳細はニュース参照。GEMINI_API_KEY環境変数によるGemini API直接利用に対応(v1.1.13)。enterprise向け高速サインイン・MCPサーバーのOAuth client ID metadata document対応・エージェントカスタマイズ継承をinheritCustomizationsスイッチに統合(v1.1.14)。printモードに--input-format stream-json追加・markdownエージェントfrontmatterにrules:キー追加(v1.1.15)。artifact viewerの見出しアウトライン・printモードの読み取り専用コマンド対応拡大(v1.1.12)。詳細はニュース参照。/usage等読み取り専用スラッシュコマンドの非対話応答に対応。コマンド自動承認・MCPサーバー起動関連の不具合も修正。詳細はニュース参照。.gitアクセスを読み取り専用に。Gemini Enterprise向けBusiness sign-in・Workforce Identity Federation・Application Default Credentials認証に対応。詳細はニュース参照。-p)でもスラッシュコマンド・スキル展開が解決されるように改善。起動が遅い/ハングするMCPサーバーが最初のターンをブロックしないよう対話セッションではバックグラウンド読み込みに変更。詳細はニュース参照。-p)に--output-format(text/json/stream-json)追加。CI/evalハーネスから進捗をプログラム的に消費可能に。--json-schemaで出力へのスキーマ強制も追加。詳細はニュース参照。agent.mdファイル + YAML frontmatterでMarkdown形式のカスタムエージェントを定義できるように。/codesearch結果の段階的レンダリング・プラグインskill検出の複数ソース集約などを改善。詳細はニュース参照。