Gemini CLI Extensions Reference

Updated September 30, 2026 by Alex Sorokoletov

Independent reference, not affiliated with Google. Tables are generated from the Gemini CLI source at v0.62.0 (v0.62.0). Official documentation: geminicli.com.

A Gemini CLI extension is a directory with a gemini-extension.json manifest that packages MCP servers, a context file, slash commands, hooks, skills, subagents and policy rules into one installable unit. Extensions install into ~/.gemini/extensions/<name>/ with gemini extensions install <git-url-or-path> and load in every session until disabled.

What goes in gemini-extension.json?#

Only name and version are required; a manifest missing either fails to load with Invalid configuration ... missing "name" (or "version").

{
  "name": "mcp-server-example",
  "version": "1.0.0",
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["${extensionPath}${/}example.js"],
      "cwd": "${extensionPath}"
    }
  }
}

String values in the manifest and in hooks/hooks.json can use these variables, substituted when the extension loads:

settings declares values the user supplies at install time. Each value is exposed as an environment variable to the extension's MCP servers and hooks:

What can a Gemini CLI extension bundle?#

Hooks are not a manifest key. Everything except MCP servers, excludeTools, themes and settings comes from files and folders next to the manifest:

An extension's hooks/hooks.json uses the same event names and entry shape as the hooks block of settings.json, wrapped in a top-level "hooks" object:

{
  "hooks": {
    "SessionStart": [
      { "hooks": [{ "type": "command", "command": "node ${extensionPath}/scripts/on-start.js" }] }
    ]
  }
}

What is an extension not allowed to do?#

An extension's MCP servers and hooks run as local commands, so install and link ask for consent first (skip the prompt with --consent). Some capabilities are withheld from extensions regardless of consent:

The practical result: an extension can add MCP tools and ask for confirmation on them, deny tools through its own policies, or narrow tool lists, but it cannot make its own tools run without a prompt. That requires a user-tier policy rule, mcp.allowed in settings, or a user decision to always allow.

How do I install, update or uninstall an extension?#

install accepts a GitHub URL, any git URL or a local path, and records how it was installed so update knows where to pull from. link keeps the extension pointed at your working copy, so edits apply on the next session without reinstalling, which is the usual loop while writing one. enable and disable take --scope user (the default) or --scope workspace. Inside a session, /extensions list, /extensions update, /extensions explore and /extensions reload are always available.

gemini extensions new <path> <template> scaffolds a new extension from a built-in example:

Where are Gemini CLI extensions installed?#

Extensions install per user, never per project: there is no project-level extensions folder. Per-project control comes from gemini extensions disable --scope workspace <name>, which records the choice in extension-enablement.json, and the -e / --extensions flag limits one session to a named set.

Frequently asked questions#

What are Gemini CLI extensions?#

Installable packages that add capabilities to Gemini CLI: MCP servers, a GEMINI.md context file, slash commands from commands/*.toml, hooks, skills, subagents, policy rules and themes. Each is a directory with a gemini-extension.json manifest, installed from a git repository or a local path into ~/.gemini/extensions/<name>/.

How do I install a Gemini CLI extension?#

Run gemini extensions install <source> with a GitHub URL, git URL or local path. Add --ref to install a specific git ref, --auto-update to keep it current, and --consent to skip the security prompt in scripts. For local development use gemini extensions link <path> instead, so changes apply without reinstalling.

How do I update or uninstall an extension?#

gemini extensions update <name> updates one extension and gemini extensions update --all updates every installed one. gemini extensions uninstall <name> removes it, accepts several names, and --all removes everything. Linked extensions track your local folder, so they need no update step.

Can a Gemini CLI extension include hooks?#

Yes, through a hooks/hooks.json file in the extension directory, not through the manifest. The file uses the same event names and structure as the hooks block in settings.json, wrapped in a top-level "hooks" object, and can reference ${extensionPath}. Extension hooks load only while hooksConfig.enabled is true.

Can an extension auto-approve its own tools?#

No. The trust flag is stripped from every MCP server an extension defines, and ALLOW rules or YOLO-mode rules in an extension's policies/ folder are ignored with a warning. Extension tools therefore follow your own policy rules and still prompt for confirmation unless you allow them in user-level settings or policies.

Where do I find Gemini CLI extensions?#

The official gallery at geminicli.com/extensions lists published extensions, and /extensions explore opens it from inside a session. Any git repository with a gemini-extension.json at its root also works as an install source, so extensions on GitHub install directly by URL.

Release-by-release changes: Gemini CLI version tracker. All Gemini CLI pages: Gemini CLI reference index.