Gemini CLI extensions and custom commands

Every extension needs a gemini-extension.json file in its root directory. Gemini CLI loads extensions from the .gemini/extensions folder in your home directory, and the extension name is expected to match its directory name.

• mcpServers: MCP servers loaded on startup just like servers in settings.json. If settings.json defines a server with the same name, the settings.json version wins. Every MCP option is supported except trust.
• contextFileName: the context file loaded into the model. If it is not set but a GEMINI.md file exists in the extension directory, that file is loaded.
• commands/ folder: TOML custom commands. commands/deploy.toml becomes /deploy and commands/gcs/sync.toml becomes /gcs:sync.
• excludeTools: tool names to hide from the model, including command-specific rules such as run_shell_command(rm -rf).
• settings: values such as API keys that users enter at install time. They are stored in a .env file in the extension directory, or in the system keychain when sensitive is true.
• Also supported: hooks in hooks/hooks.json, agent skills in skills/, sub-agents in agents/ (preview), policy rules in policies/, and themes in the manifest.

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

Use the ${extensionPath} variable to point at files inside the extension so it stays portable. Extensions only receive standard safe environment variables plus the ones you declare through envVar in the settings array.

Run these from your terminal, not inside the interactive CLI. Inside a session, /extensions list shows what is installed. Installation copies the extension, so you must run an update to pull changes from the source, and installing from GitHub requires git.

# Install from a GitHub URL or local path
gemini extensions install https://github.com/gemini-cli-extensions/workspace
gemini extensions install YOUR_SOURCE --ref YOUR_GIT_REF --auto-update

# List installed extensions
gemini extensions list

# Update one or all
gemini extensions update YOUR_EXTENSION_NAME
gemini extensions update --all

# Disable or enable, optionally per scope (user or workspace)
gemini extensions disable YOUR_EXTENSION_NAME --scope workspace
gemini extensions enable YOUR_EXTENSION_NAME

# Change settings such as API keys
gemini extensions config YOUR_EXTENSION_NAME

# Remove
gemini extensions uninstall YOUR_EXTENSION_NAME

Extensions are enabled globally by default. All management changes, including updates to slash commands, take effect only after you restart the CLI session.

Start from a built-in template such as mcp-server, context, or custom-commands, then link the folder so edits show up without reinstalling.

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

The mcp-server template creates example.js, gemini-extension.json, and package.json. After linking, restart Gemini CLI to load the new tools. If an extension command clashes with a user or project command, it is renamed with the extension name and a dot, for example /gcp.deploy.

User commands live in ~/.gemini/commands and work in every project. Project commands live in .gemini/commands at your project root and can be committed for your team. A project command overrides a user command with the same name. Subfolders become namespaces, so git/commit.toml becomes /git:commit.

• prompt (required): the text sent to the model.
• description (optional): one line shown in /help. If omitted, one is generated from the filename.
• {{args}} is replaced with whatever you type after the command. Without it, your full command is appended to the prompt after two newlines.
• !{...} runs a shell command and injects its output. Gemini CLI asks you to confirm the command first, and {{args}} inside the block is shell-escaped.
• Run /commands reload after editing files, and /commands list to see all command files.

# Invoked via: /git:fix "Button is misaligned"
description = "Generates a fix for a given issue."
prompt = "Please provide a code fix for the issue described here: {{args}}."