Gemini CLI extensions: install, build, release and find them

What are Gemini CLI extensions?

Gemini CLI extensions are installable packages that add tools, context and commands to Google's Gemini CLI in one step: you run gemini extensions install <github-url> and the extension's MCP servers, instructions and slash commands load the next time you start the CLI. The extensions docs say they package "prompts, MCP servers, custom commands, themes, hooks, sub-agents, and agent skills" and are "designed to be easily installable and shareable."

Without extensions, you would add each MCP server to settings.json, copy a GEMINI.md and write TOML commands by hand. An extension does all of that from one GitHub repository, which is why companies use them to ship official integrations.

Who can still use Gemini CLI in 2026?

Check this before you invest time. The Gemini CLI README opens with: "Free individual access and Google AI Pro / Ultra (Google One) moved to Antigravity CLI on June 18, 2026." Google's Gemini Code Assist deprecation page lists the same change.

Gemini CLI remains available with Gemini Code Assist Standard and Enterprise licenses, Code Assist for GitHub on Google Cloud and paid API keys, as the Gemini CLI guide explains. The README also says Gemini CLI is "Not tuned for the Gemini 4 series (for example, Gemini 4 Argon) or future releases in this or later generations." If you moved to Antigravity CLI, skip to the last section on converting extensions to plugins.

How do you install and manage extensions?

All commands below come from the extension reference and the extensions overview. They run from your shell, not inside an interactive session:

# install from GitHub or a local folder
gemini extensions install https://github.com/gemini-cli-extensions/workspace
gemini extensions install <source> --ref <branch-tag-or-commit> --auto-update

# see what is installed
gemini extensions list

# keep them current
gemini extensions update <name>
gemini extensions update --all

# turn one off for this project only, or remove it
gemini extensions disable <name> --scope workspace
gemini extensions enable <name>
gemini extensions uninstall <name>

Other install flags: --pre-release installs the newest release even if it isn't marked Latest, --consent acknowledges the security prompt without asking, and --skip-settings skips configuration during install. GitHub installs need git on your machine.

A few behaviors worth knowing:

• Extensions load from ~/.gemini/extensions. Installing copies the files, so local edits to the source don't show up until you update.
• Extensions are enabled globally by default. --scope takes user or workspace.
• Changes take effect after you restart the CLI. Inside a session, /extensions list shows what loaded.
• gemini extensions config <name> changes an extension's settings later. Sensitive settings, such as API keys, are kept in the system keychain.

What goes into an extension?

Every extension has a gemini-extension.json manifest at its root. This is the example from Google's reference, trimmed:

{
  "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"]
}

The main fields:

Beyond the manifest, folders add more:

• commands/ holds TOML custom commands. commands/deploy.toml becomes /deploy, and commands/gcs/sync.toml becomes /gcs:sync.
• skills/ holds Agent Skills, such as skills/security-audit/SKILL.md.
• hooks/hooks.json defines hooks.
• agents/ holds sub-agent definitions (preview).
• policies/ holds .toml policy files. Extension allow decisions and yolo settings are ignored.

The variables ${extensionPath}, ${workspacePath} and ${/} (the path separator) work in the manifest and in hooks.json. Extensions do not inherit your whole shell environment: they get safe basics such as HOME, PATH and TMPDIR, plus variables you declare in settings.

If an extension command shares a name with one of your own commands, yours wins and the extension's gets a prefix, such as /gcp.deploy.

How do you build your own extension?

The writing extensions guide starts from a template. gemini extensions new <path> [template] takes a built-in template such as mcp-server, context or custom-commands:

gemini extensions new my-first-extension mcp-server
cd my-first-extension
npm install
gemini extensions link .

The mcp-server template creates gemini-extension.json, package.json and example.js, a small MCP server with a fetch_posts tool. gemini extensions link . symlinks the folder into your extensions directory, so edits apply without reinstalling. Restart Gemini CLI and ask it to "fetch posts" to test.

From there, add the parts you need:

1. A custom command. Create commands/fs/grep-code.toml with a prompt field (and an optional description). After a restart it runs as /fs:grep-code.
2. Context. Write a GEMINI.md in the extension root and set "contextFileName": "GEMINI.md". The GEMINI.md guide covers what makes a useful context file.
3. A skill. Add skills/security-audit/SKILL.md with a name, description and instructions. The model activates it only when relevant.
4. Settings. Add a settings array for things like API keys and mark secrets "sensitive": true.

Google's best practices page adds a few rules: use TypeScript with src/ and dist/ kept apart, keep GEMINI.md short ("Avoid dumping exhaustive documentation into the file"), restrict risky tools such as run_shell_command with excludeTools, and "Always validate tool inputs to prevent arbitrary code execution or unauthorized filesystem access."

How do you release an extension and get it in the gallery?

The releasing guide offers two paths:

• Git repository. The simplest option. Users install from the repo URL and can pin with --ref. Updates are detected by comparing the remote commit with the local one.
• GitHub Releases. Faster first installs, since users download an archive instead of cloning, and the way to ship platform-specific binaries. Assets are matched by name, such as darwin.arm64.my-tool.tar.gz, with gemini-extension.json at the archive root. The CLI looks for the release marked Latest and compares release tags, so keep the tag in sync with the manifest version.

Getting listed takes three steps and no form: host the extension in a public GitHub repo, keep gemini-extension.json at the root, and "Add the gemini-cli-extension topic to your repository's About section." Google says its system crawls tagged repositories daily.

Where can you find extensions?

The extension gallery showed 2,194 extensions on 26 October 2026. Each card shows the repo's GitHub star count, badges for what it contains (MCP, context, commands, skills, hooks) and a copyable install command.

Google's own extensions live mostly under the gemini-cli-extensions organization and include Workspace, Firebase, Flutter, Genkit, Cloud Run, gcloud, code review and Jules. Others come from Google teams such as Chrome DevTools and Google Cloud.

The gallery carries a warning worth reading: "Google does not vet, endorse, or guarantee the functionality or security of these extensions." Read the manifest and source before you install, especially any MCP server it starts.

How do extensions move to Antigravity CLI?

If you were moved to Antigravity CLI, your extensions don't load there as is. Antigravity uses plugins, and its migration guide provides one command:

agy plugin import gemini

It converts extension manifests, turns legacy commands into skills and moves MCP definitions into mcp_config.json. The Antigravity CLI guide covers plugins and skill folders.

Skills are the most portable part of any extension, because the same SKILL.md format works in Gemini CLI, Antigravity, Claude Code and Codex. If you keep skills in several places, Kipt stores them as Markdown in a private GitHub repo you own, and the free SKILL.md generator turns a prompt into a valid SKILL.md in your browser.