From 4e84431df3e5737a0687af59853504a4e5b9ae51 Mon Sep 17 00:00:00 2001
From: Tommaso Sciortino <sciortino@gmail.com>
Date: Tue, 10 Jun 2025 15:48:39 -0700
Subject: Allow simple extensions for registering MCPservers (#890)

---
 docs/extension.md | 38 ++++++++++++++++++++++++++++++++++++++
 docs/index.md     |  1 +
 2 files changed, 39 insertions(+)
 create mode 100644 docs/extension.md

(limited to 'docs')

diff --git a/docs/extension.md b/docs/extension.md
new file mode 100644
index 00000000..e71b58a3
--- /dev/null
+++ b/docs/extension.md
@@ -0,0 +1,38 @@
+# Gemini CLI Extensions
+
+Gemini CLI supports extensions that can be used to configure and extend its functionality.
+
+## How it works
+
+On startup, Gemini CLI looks for extensions in two locations:
+
+1.  `<workspace>/.gemini/extensions`
+2.  `<home>/.gemini/extensions`
+
+It will load all extensions from both locations, but if an extension with the same name exists in both, the one in the workspace directory will take precedence.
+
+Each extension is a directory that contains a `gemini-extension.json` file. This file contains the configuration for the extension.
+
+### `gemini-extension.json`
+
+The `gemini-extension.json` file has the following structure:
+
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "mcpServers": {
+    "my-server": {
+      "command": "node my-server.js"
+    }
+  },
+  "contextFileName": "GEMINI.md"
+}
+```
+
+- `name`: The name of the extension. This is used to uniquely identify the extension.
+- `version`: The version of the extension.
+- `mcpServers`: A map of MCP servers to configure. The key is the name of the server, and the value is the server configuration. These servers will be loaded on startup just like mcpServers configured in settings.json. If an extension and settings.json configure a mcp server with the same name, settings.json will take precedence.
+- `contextFileName`: The name of the file that contains the context for the extension. This will be used to load the context from the workspace. NOT YET SUPPORTED
+
+When Gemini CLI starts, it will load all the extensions and merge their configurations. If there are any conflicts, the workspace configuration will take precedence.
diff --git a/docs/index.md b/docs/index.md
index 1745d288..5c710976 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -19,6 +19,7 @@ This documentation is organized into the following sections:
   - **[CLI Introduction](./cli/index.md):** An overview of the command-line interface.
   - **[Commands](./cli/commands.md):** Detailed descriptions of all available CLI commands.
   - **[Configuration](./cli/configuration.md):** How to configure the CLI.
+  - **[Extensions](./extension.md):** How to extend the CLI with new functionality.
 - **Core Details:**
   - **[Core Introduction](./core/index.md):** An overview of the core component.
   - **[Configuration](./core/configuration.md):** How to configure the core.
-- 
cgit v1.2.3