Gemini CLI extensions

概要

prompt、MCP サーバー、カスタムコマンド、テーマ、hooks、sub-agent、agent skill をまとめて配布可能な形にする仕組み。インストールと共有が容易になるよう設計されている。

仕様

管理

対話セッション内: /extensions list でインストール済みと状態を確認する
ターミナル: gemini extensions コマンド群
gemini extensions install のような管理コマンドは CLI の対話モード内ではサポートされない。 対話モードで使えるのは /extensions list
slash コマンドの更新を含むすべての管理操作は、CLI セッションを再起動してから有効になる

コマンド

コマンド	内容
`gemini extensions install <source> [--ref <ref>] [--auto-update] [--pre-release] [--consent] [--skip-settings]`	GitHub URL またはローカルパスからインストールする
`gemini extensions uninstall <name...>`	アンインストールする
`gemini extensions disable <name> [--scope <scope>]`	無効にする。extension は既定でグローバルに有効。`--scope` は `user` または `workspace`
`gemini extensions enable <name> [--scope <scope>]`	再度有効にする
`gemini extensions update <name>` / `--all`	`gemini-extension.json` で指定されたバージョンに更新する
`gemini extensions new <path> [template]`	組み込みテンプレート（`mcp-server`、`context`、`custom-commands` など）から新規作成する
`gemini extensions link <path>`	開発ディレクトリと extensions ディレクトリの間にシンボリックリンクを作る
`gemini extensions config <name> [setting] [--scope <scope>]`	extension の設定を更新する

インストール時に Gemini CLI は extension のコピーを作る。ソースの変更を取り込むには gemini extensions update を実行する
GitHub からインストールするには git がマシンに必要
インストールオプション: --ref（git の branch / tag / commit）、--auto-update、--pre-release、--consent（セキュリティリスクを了承して確認を飛ばす）、--skip-settings

フォーマット

<home>/.gemini/extensions から読み込まれる
各 extension はルートに gemini-extension.json を持つ必要がある

gemini-extension.json の主なフィールド:

フィールド	内容
`name`	一意な識別子。小文字または数字で、アンダースコアやスペースの代わりにダッシュを使う。ディレクトリ名と一致することが期待されている
`version`	バージョン
`description`	短い説明。extensions のギャラリーに表示される
`migratedTo`	新しいリポジトリソースの URL。設定すると、CLI は更新確認先を新しいソースに切り替え、更新が見つかればインストールを移行する
`mcpServers`	MCP サーバーのマップ。`settings.json` の MCP サーバーと同名の場合、`settings.json` 側が優先する。`trust` を除くすべての MCP サーバー設定オプションに対応。移植性のため `${extensionPath}` を使い、実行ファイルと引数は `command` と `args` に分ける
`contextFileName`	extension のコンテキストを含むファイル名。このプロパティが無くても extension ディレクトリに `GEMINI.md` があればそれが読み込まれる
`excludeTools`	モデルから除外するツール名の配列。`run_shell_command` などはコマンド単位の制限も書ける（`"run_shell_command(rm -rf)"`）。MCP サーバー設定の `excludeTools` とは別物
`plan.directory`	計画成果物の保存先。ユーザーが settings で指定していない場合のフォールバック。どちらも未指定なら既定は `~/.gemini/tmp/<project>/<session-id>/plans/`
`settings`	インストール時にユーザーが入力する設定の配列
`themes`	カスタムテーマの配列

起動時にすべての extension を読み込んで設定をマージする。衝突した場合は workspace の設定が優先する

extension settings と環境変数

settings 配列で、インストール時にユーザーが渡す値（API キー、URL など）を定義する。値は extension ディレクトリ内の .env に保存される
各要素のフィールド: name（表示名）、description、envVar（値を格納する環境変数名）、sensitive（true なら値はシステムのキーチェーンに保存され UI 上で伏せられる）

環境変数のサニタイズ:

セキュリティのため、機微な環境変数は既定でフィルタされ、extension や MCP サーバーには渡されない
extension はユーザーのシェル環境変数を丸ごと継承しない。 アクセスできるのは
1. 標準的な安全な変数（HOME、PATH、TMPDIR など）
2. gemini-extension.json の settings 配列で envVar として明示的に宣言・要求した変数
特定の環境変数が必要な extension は、必ず settings 配列で宣言して allowlist させる

バンドルできる要素

要素	置き場所
カスタムコマンド	`commands/` サブディレクトリの TOML。ディレクトリ構造でコマンド名が決まる（`commands/deploy.toml` → `/deploy`、`commands/gcs/sync.toml` → `/gcs:sync`）
hooks	extension ディレクトリ内の `hooks/hooks.json`。`gemini-extension.json` マニフェストには書かない
agent skills	`skills/` ディレクトリ（`skills/security-audit/SKILL.md` → `security-audit` skill）
sub-agents	extension ルートの `agents/` ディレクトリの `.md`。sub-agent は活発に開発中の preview 機能と注記されている
policy rules	`policies/` ディレクトリの `.toml`。extension が有効化されたときに効く
themes	`gemini-extension.json` の `themes` 配列

Policy Engine への寄与:

extension のルールは**独自のティア（tier 2）**で、workspace 定義のポリシーと同列。既定ルールより高く、user や admin のポリシーより低い
セキュリティのため、Gemini CLI は extension のポリシー内の allow decision と yolo モードの設定を無視する。 extension が確認なしにツール呼び出しを自動承認したりセキュリティ対策を迂回したりできないようにするため

テーマ:

extension のテーマは /theme か settings.json の ui.theme で選べる
extension のテーマを参照するときは、テーマ名の後ろに括弧付きで extension 名が付く（shades-of-green (my-green-extension)）

衝突の解決

extension のコマンドは最も優先度が低い。 user や project のコマンドと名前が衝突すると、ドット区切りで extension 名が前置される（/gcp.deploy）

変数の置換

gemini-extension.json と hooks/hooks.json で使える。

変数	内容
`${extensionPath}`	extension ディレクトリの絶対パス
`${workspacePath}`	現在のワークスペースの絶対パス
`${/}`	プラットフォーム固有のパス区切り

設定

{
  "name": "my-extension",
  "version": "1.0.0",
  "description": "My awesome extension",
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["${extensionPath}/my-server.js"],
      "cwd": "${extensionPath}"
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"],
  "plan": { "directory": ".gemini/plans" }
}

{
  "name": "my-api-extension",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "Your API key for the service.",
      "envVar": "MY_API_KEY",
      "sensitive": true
    }
  ]
}

gemini extensions install https://github.com/gemini-cli-extensions/workspace
gemini extensions update --all
gemini extensions new ./my-ext mcp-server