mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-04-02 09:20:42 -07:00
Updated ToC on docs intro; updated title casing to match Google style (#13717)
This commit is contained in:
David Huntsperger
committed by
GitHub
GitHub
parent
bde8b78a88
commit
26f050ff10
@@ -1,4 +1,4 @@
|
||||
# Gemini CLI Companion Plugin: Interface Specification
|
||||
# Gemini CLI companion plugin: Interface specification
|
||||
|
||||
> Last Updated: September 15, 2025
|
||||
|
||||
@@ -9,11 +9,11 @@ awareness) are provided by the official extension
|
||||
This specification is for contributors who wish to bring similar functionality
|
||||
to other editors like JetBrains IDEs, Sublime Text, etc.
|
||||
|
||||
## I. The Communication Interface
|
||||
## I. The communication interface
|
||||
|
||||
Gemini CLI and the IDE plugin communicate through a local communication channel.
|
||||
|
||||
### 1. Transport Layer: MCP over HTTP
|
||||
### 1. Transport layer: MCP over HTTP
|
||||
|
||||
The plugin **MUST** run a local HTTP server that implements the **Model Context
|
||||
Protocol (MCP)**.
|
||||
@@ -25,24 +25,24 @@ Protocol (MCP)**.
|
||||
- **Port:** The server **MUST** listen on a dynamically assigned port (i.e.,
|
||||
listen on port `0`).
|
||||
|
||||
### 2. Discovery Mechanism: The Port File
|
||||
### 2. Discovery mechanism: The port file
|
||||
|
||||
For Gemini CLI to connect, it needs to discover which IDE instance it's running
|
||||
in and what port your server is using. The plugin **MUST** facilitate this by
|
||||
creating a "discovery file."
|
||||
|
||||
- **How the CLI Finds the File:** The CLI determines the Process ID (PID) of the
|
||||
- **How the CLI finds the file:** The CLI determines the Process ID (PID) of the
|
||||
IDE it's running in by traversing the process tree. It then looks for a
|
||||
discovery file that contains this PID in its name.
|
||||
- **File Location:** The file must be created in a specific directory:
|
||||
- **File location:** The file must be created in a specific directory:
|
||||
`os.tmpdir()/gemini/ide/`. Your plugin must create this directory if it
|
||||
doesn't exist.
|
||||
- **File Naming Convention:** The filename is critical and **MUST** follow the
|
||||
- **File naming convention:** The filename is critical and **MUST** follow the
|
||||
pattern: `gemini-ide-server-${PID}-${PORT}.json`
|
||||
- `${PID}`: The process ID of the parent IDE process. Your plugin must
|
||||
determine this PID and include it in the filename.
|
||||
- `${PORT}`: The port your MCP server is listening on.
|
||||
- **File Content & Workspace Validation:** The file **MUST** contain a JSON
|
||||
- **File content and workspace validation:** The file **MUST** contain a JSON
|
||||
object with the following structure:
|
||||
|
||||
```json
|
||||
@@ -79,7 +79,7 @@ creating a "discovery file."
|
||||
server (e.g., `Authorization: Bearer a-very-secret-token`). Your server
|
||||
**MUST** validate this token on every request and reject any that are
|
||||
unauthorized.
|
||||
- **Tie-Breaking with Environment Variables (Recommended):** For the most
|
||||
- **Tie-breaking with environment variables (recommended):** For the most
|
||||
reliable experience, your plugin **SHOULD** both create the discovery file and
|
||||
set the `GEMINI_CLI_IDE_SERVER_PORT` environment variable in the integrated
|
||||
terminal. The file serves as the primary discovery mechanism, but the
|
||||
@@ -88,18 +88,18 @@ creating a "discovery file."
|
||||
`GEMINI_CLI_IDE_SERVER_PORT` variable to identify and connect to the correct
|
||||
window's server.
|
||||
|
||||
## II. The Context Interface
|
||||
## II. The context interface
|
||||
|
||||
To enable context awareness, the plugin **MAY** provide the CLI with real-time
|
||||
information about the user's activity in the IDE.
|
||||
|
||||
### `ide/contextUpdate` Notification
|
||||
### `ide/contextUpdate` notification
|
||||
|
||||
The plugin **MAY** send an `ide/contextUpdate`
|
||||
[notification](https://modelcontextprotocol.io/specification/2025-06-18/basic/index#notifications)
|
||||
to the CLI whenever the user's context changes.
|
||||
|
||||
- **Triggering Events:** This notification should be sent (with a recommended
|
||||
- **Triggering events:** This notification should be sent (with a recommended
|
||||
debounce of 50ms) when:
|
||||
- A file is opened, closed, or focused.
|
||||
- The user's cursor position or text selection changes in the active file.
|
||||
@@ -136,16 +136,16 @@ to the CLI whenever the user's context changes.
|
||||
Virtual files (e.g., unsaved files without a path, editor settings pages)
|
||||
**MUST** be excluded.
|
||||
|
||||
### How the CLI Uses This Context
|
||||
### How the CLI uses this context
|
||||
|
||||
After receiving the `IdeContext` object, the CLI performs several normalization
|
||||
and truncation steps before sending the information to the model.
|
||||
|
||||
- **File Ordering:** The CLI uses the `timestamp` field to determine the most
|
||||
- **File ordering:** The CLI uses the `timestamp` field to determine the most
|
||||
recently used files. It sorts the `openFiles` list based on this value.
|
||||
Therefore, your plugin **MUST** provide an accurate Unix timestamp for when a
|
||||
file was last focused.
|
||||
- **Active File:** The CLI considers only the most recent file (after sorting)
|
||||
- **Active file:** The CLI considers only the most recent file (after sorting)
|
||||
to be the "active" file. It will ignore the `isActive` flag on all other files
|
||||
and clear their `cursor` and `selectedText` fields. Your plugin should focus
|
||||
on setting `isActive: true` and providing cursor/selection details only for
|
||||
@@ -156,14 +156,14 @@ and truncation steps before sending the information to the model.
|
||||
While the CLI handles the final truncation, it is highly recommended that your
|
||||
plugin also limits the amount of context it sends.
|
||||
|
||||
## III. The Diffing Interface
|
||||
## III. The diffing interface
|
||||
|
||||
To enable interactive code modifications, the plugin **MAY** expose a diffing
|
||||
interface. This allows the CLI to request that the IDE open a diff view, showing
|
||||
proposed changes to a file. The user can then review, edit, and ultimately
|
||||
accept or reject these changes directly within the IDE.
|
||||
|
||||
### `openDiff` Tool
|
||||
### `openDiff` tool
|
||||
|
||||
The plugin **MUST** register an `openDiff` tool on its MCP server.
|
||||
|
||||
@@ -194,7 +194,7 @@ The plugin **MUST** register an `openDiff` tool on its MCP server.
|
||||
The actual outcome of the diff (acceptance or rejection) is communicated
|
||||
asynchronously via notifications.
|
||||
|
||||
### `closeDiff` Tool
|
||||
### `closeDiff` tool
|
||||
|
||||
The plugin **MUST** register a `closeDiff` tool on its MCP server.
|
||||
|
||||
@@ -219,7 +219,7 @@ The plugin **MUST** register a `closeDiff` tool on its MCP server.
|
||||
**MUST** have `isError: true` and include a `TextContent` block in the
|
||||
`content` array describing the error.
|
||||
|
||||
### `ide/diffAccepted` Notification
|
||||
### `ide/diffAccepted` notification
|
||||
|
||||
When the user accepts the changes in a diff view (e.g., by clicking an "Apply"
|
||||
or "Save" button), the plugin **MUST** send an `ide/diffAccepted` notification
|
||||
@@ -238,7 +238,7 @@ to the CLI.
|
||||
}
|
||||
```
|
||||
|
||||
### `ide/diffRejected` Notification
|
||||
### `ide/diffRejected` notification
|
||||
|
||||
When the user rejects the changes (e.g., by closing the diff view without
|
||||
accepting), the plugin **MUST** send an `ide/diffRejected` notification to the
|
||||
@@ -254,14 +254,14 @@ CLI.
|
||||
}
|
||||
```
|
||||
|
||||
## IV. The Lifecycle Interface
|
||||
## IV. The lifecycle interface
|
||||
|
||||
The plugin **MUST** manage its resources and the discovery file correctly based
|
||||
on the IDE's lifecycle.
|
||||
|
||||
- **On Activation (IDE startup/plugin enabled):**
|
||||
- **On activation (IDE startup/plugin enabled):**
|
||||
1. Start the MCP server.
|
||||
2. Create the discovery file.
|
||||
- **On Deactivation (IDE shutdown/plugin disabled):**
|
||||
- **On deactivation (IDE shutdown/plugin disabled):**
|
||||
1. Stop the MCP server.
|
||||
2. Delete the discovery file.
|
||||
|
||||
@@ -1,4 +1,4 @@
|
||||
# IDE Integration
|
||||
# IDE integration
|
||||
|
||||
Gemini CLI can integrate with your IDE to provide a more seamless and
|
||||
context-aware experience. This integration allows the CLI to understand your
|
||||
@@ -11,18 +11,18 @@ support VS Code extensions. To build support for other editors, see the
|
||||
|
||||
## Features
|
||||
|
||||
- **Workspace Context:** The CLI automatically gains awareness of your workspace
|
||||
- **Workspace context:** The CLI automatically gains awareness of your workspace
|
||||
to provide more relevant and accurate responses. This context includes:
|
||||
- The **10 most recently accessed files** in your workspace.
|
||||
- Your active cursor position.
|
||||
- Any text you have selected (up to a 16KB limit; longer selections will be
|
||||
truncated).
|
||||
|
||||
- **Native Diffing:** When Gemini suggests code modifications, you can view the
|
||||
- **Native diffing:** When Gemini suggests code modifications, you can view the
|
||||
changes directly within your IDE's native diff viewer. This allows you to
|
||||
review, edit, and accept or reject the suggested changes seamlessly.
|
||||
|
||||
- **VS Code Commands:** You can access Gemini CLI features directly from the VS
|
||||
- **VS Code commands:** You can access Gemini CLI features directly from the VS
|
||||
Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`):
|
||||
- `Gemini CLI: Run`: Starts a new Gemini CLI session in the integrated
|
||||
terminal.
|
||||
@@ -32,18 +32,18 @@ support VS Code extensions. To build support for other editors, see the
|
||||
- `Gemini CLI: View Third-Party Notices`: Displays the third-party notices for
|
||||
the extension.
|
||||
|
||||
## Installation and Setup
|
||||
## Installation and setup
|
||||
|
||||
There are three ways to set up the IDE integration:
|
||||
|
||||
### 1. Automatic Nudge (Recommended)
|
||||
### 1. Automatic nudge (recommended)
|
||||
|
||||
When you run Gemini CLI inside a supported editor, it will automatically detect
|
||||
your environment and prompt you to connect. Answering "Yes" will automatically
|
||||
run the necessary setup, which includes installing the companion extension and
|
||||
enabling the connection.
|
||||
|
||||
### 2. Manual Installation from CLI
|
||||
### 2. Manual installation from CLI
|
||||
|
||||
If you previously dismissed the prompt or want to install the extension
|
||||
manually, you can run the following command inside Gemini CLI:
|
||||
@@ -54,13 +54,13 @@ manually, you can run the following command inside Gemini CLI:
|
||||
|
||||
This will find the correct extension for your IDE and install it.
|
||||
|
||||
### 3. Manual Installation from a Marketplace
|
||||
### 3. Manual installation from a marketplace
|
||||
|
||||
You can also install the extension directly from a marketplace.
|
||||
|
||||
- **For Visual Studio Code:** Install from the
|
||||
[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=google.gemini-cli-vscode-ide-companion).
|
||||
- **For VS Code Forks:** To support forks of VS Code, the extension is also
|
||||
- **For VS Code forks:** To support forks of VS Code, the extension is also
|
||||
published on the
|
||||
[Open VSX Registry](https://open-vsx.org/extension/google/gemini-cli-vscode-ide-companion).
|
||||
Follow your editor's instructions for installing extensions from this
|
||||
@@ -75,7 +75,7 @@ You can also install the extension directly from a marketplace.
|
||||
|
||||
## Usage
|
||||
|
||||
### Enabling and Disabling
|
||||
### Enabling and disabling
|
||||
|
||||
You can control the IDE integration from within the CLI:
|
||||
|
||||
@@ -91,7 +91,7 @@ You can control the IDE integration from within the CLI:
|
||||
When enabled, Gemini CLI will automatically attempt to connect to the IDE
|
||||
companion extension.
|
||||
|
||||
### Checking the Status
|
||||
### Checking the status
|
||||
|
||||
To check the connection status and see the context the CLI has received from the
|
||||
IDE, run:
|
||||
@@ -106,7 +106,7 @@ recently opened files it is aware of.
|
||||
> [!NOTE] The file list is limited to 10 recently accessed files within your
|
||||
> workspace and only includes local files on disk.)
|
||||
|
||||
### Working with Diffs
|
||||
### Working with diffs
|
||||
|
||||
When you ask Gemini to modify a file, it can open a diff view directly in your
|
||||
editor.
|
||||
@@ -131,14 +131,14 @@ accepting them.
|
||||
If you select ‘Yes, allow always’ in the CLI, changes will no longer show up in
|
||||
the IDE as they will be auto-accepted.
|
||||
|
||||
## Using with Sandboxing
|
||||
## Using with sandboxing
|
||||
|
||||
If you are using Gemini CLI within a sandbox, please be aware of the following:
|
||||
|
||||
- **On macOS:** The IDE integration requires network access to communicate with
|
||||
the IDE companion extension. You must use a Seatbelt profile that allows
|
||||
network access.
|
||||
- **In a Docker Container:** If you run Gemini CLI inside a Docker (or Podman)
|
||||
- **In a Docker container:** If you run Gemini CLI inside a Docker (or Podman)
|
||||
container, the IDE integration can still connect to the VS Code extension
|
||||
running on your host machine. The CLI is configured to automatically find the
|
||||
IDE server on `host.docker.internal`. No special configuration is usually
|
||||
@@ -150,7 +150,7 @@ If you are using Gemini CLI within a sandbox, please be aware of the following:
|
||||
If you encounter issues with IDE integration, here are some common error
|
||||
messages and how to resolve them.
|
||||
|
||||
### Connection Errors
|
||||
### Connection errors
|
||||
|
||||
- **Message:**
|
||||
`🔴 Disconnected: Failed to connect to IDE companion extension in [IDE Name]. Please ensure the extension is running. To install the extension, run /ide install.`
|
||||
@@ -170,7 +170,7 @@ messages and how to resolve them.
|
||||
- **Solution:** Run `/ide enable` to try and reconnect. If the issue
|
||||
continues, open a new terminal window or restart your IDE.
|
||||
|
||||
### Configuration Errors
|
||||
### Configuration errors
|
||||
|
||||
- **Message:**
|
||||
`🔴 Disconnected: Directory mismatch. Gemini CLI is running in a different location than the open workspace in [IDE Name]. Please run the CLI from one of the following directories: [List of directories]`
|
||||
@@ -184,7 +184,7 @@ messages and how to resolve them.
|
||||
- **Cause:** You have no workspace open in your IDE.
|
||||
- **Solution:** Open a workspace in your IDE and restart the CLI.
|
||||
|
||||
### General Errors
|
||||
### General errors
|
||||
|
||||
- **Message:**
|
||||
`IDE integration is not supported in your current environment. To use this feature, run Gemini CLI in one of these supported IDEs: [List of IDEs]`
|
||||
|
||||
Reference in New Issue
Block a user