MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-04-27 13:34:15 -07:00
Code Issues Packages Projects Releases Wiki Activity

ACP integration documents (#22254)

Browse Source 
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: nmcnamara-eng <118702206+nmcnamara-eng@users.noreply.github.com>
This commit is contained in:
Sam Roberts
2026-03-26 19:10:29 -07:00
committed by GitHub
parent 8413dd62ef
commit 6f92642524
4 changed files with 297 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ide-integration/index.md
+99 -24
View File
@@ -1,15 +1,29 @@
# 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
workspace better and enables powerful features like native in-editor diffing.
Currently, the supported IDEs are [Antigravity](https://antigravity.google),
[Visual Studio Code](https://code.visualstudio.com/), and other editors that
support VS Code extensions. To build support for other editors, see the
[IDE Companion Extension Spec](./ide-companion-spec.md).
There are two primary ways to integrate Gemini CLI with an IDE:
## Features
1. **VS Code companion extension**: Install the "Gemini CLI Companion"
extension on [Antigravity](https://antigravity.google),
[Visual Studio Code](https://code.visualstudio.com/), or other VS Code
compatible editors.
2. **Agent Client Protocol (ACP)**: An open protocol for interoperability
between AI coding agents and IDEs. This method is used for integrations with
tools like JetBrains and Zed, which leverage the ACP Agent Registry for easy
discovery and installation of compatible agents like Gemini CLI.
## VS Code companion extension
The **Gemini CLI Companion extension** grants Gemini CLI direct access to your
VS Code compatible IDEs and improves your experience by providing real-time
context such as open files, cursor positions, and text selection. The extension
also enables a native diffing interface so you can seamlessly review and apply
AI-generated code changes directly within your editor.
### Features
- **Workspace context:** The CLI automatically gains awareness of your workspace
to provide more relevant and accurate responses. This context includes:
@@ -19,8 +33,8 @@ support VS Code extensions. To build support for other editors, see the
truncated).
- **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.
changes directly within your IDE's native diff viewer. This lets you review,
edit, and accept or reject the suggested changes seamlessly.
- **VS Code commands:** You can access Gemini CLI features directly from the VS
Code Command Palette (`Cmd+Shift+P` or `Ctrl+Shift+P`):
@@ -32,18 +46,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,7 +68,7 @@ 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.
@@ -75,9 +89,9 @@ You can also install the extension directly from a marketplace.
> After manually installing the extension, you must run `/ide enable` in the CLI
> to activate the integration.
## Usage
### Usage
### Enabling and disabling
#### Enabling and disabling
You can control the IDE integration from within the CLI:
@@ -93,7 +107,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:
@@ -108,9 +122,9 @@ recently opened files it is aware of.
<!-- prettier-ignore -->
> [!NOTE]
> The file list is limited to 10 recently accessed files within your
> workspace and only includes local files on disk.)
> 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.
@@ -135,6 +149,63 @@ accepting them.
If you select ‘Allow for this session’ in the CLI, changes will no longer show
up in the IDE as they will be auto-accepted.
## Agent Client Protocol (ACP)
ACP is an open protocol that standardizes how AI coding agents communicate with
code editors and IDEs. It addresses the challenge of fragmented distribution,
where agents traditionally needed custom integrations for each client. With ACP,
developers can implement their agent once, and it becomes compatible with any
ACP-compliant editor.
For a comprehensive introduction to ACP, including its architecture and
benefits, refer to the official
[ACP Introduction](https://agentclientprotocol.com/get-started/introduction)
documentation.
### The ACP Agent Registry
Gemini CLI is officially available in the **ACP Agent Registry**. This allows
you to install and update Gemini CLI directly within supporting IDEs and
eliminates the need for manual downloads or IDE-specific extensions.
Using the registry ensures:
- **Ease of use**: Discover and install agents directly within your IDE
settings.
- **Latest versions**: Ensures users always have access to the most up-to-date
agent implementations.
For more details on how the registry works, visit the official
[ACP Agent Registry](https://agentclientprotocol.com/get-started/registry) page.
You can learn about how specific IDEs leverage this integration in the following
section.
### IDE-specific integration
Gemini CLI is an ACP-compatible agent available in the ACP Agent Registry.
Here’s how different IDEs leverage the ACP and the registry:
#### JetBrains IDEs
JetBrains IDEs (like IntelliJ IDEA, PyCharm, or GoLand) offer built-in registry
support, allowing users to find and install ACP-compatible agents directly.
For more details, refer to the official
[JetBrains AI Blog announcement](https://blog.jetbrains.com/ai/2026/01/acp-agent-registry/).
#### Zed
Zed, a modern code editor, also integrates with the ACP Agent Registry. This
allows Zed users to easily browse, install, and manage ACP agents.
Learn more about Zed's integration with the ACP Registry in their
[blog post](https://zed.dev/blog/acp-registry).
#### Other ACP-compatible IDEs
Any other IDE that supports the ACP Agent Registry can install Gemini CLI
directly through their in-built registry features.
## Using with sandboxing
If you are using Gemini CLI within a sandbox, please be aware of the following:
@@ -151,10 +222,9 @@ If you are using Gemini CLI within a sandbox, please be aware of the following:
## Troubleshooting
If you encounter issues with IDE integration, here are some common error
messages and how to resolve them.
### VS Code companion extension errors
### 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.`
@@ -174,7 +244,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.
### Manual PID override
#### Manual PID override
If automatic IDE detection fails, or if you are running Gemini CLI in a
standalone terminal and want to manually associate it with a specific IDE
@@ -196,7 +266,7 @@ $env:GEMINI_CLI_IDE_PID=12345
When this variable is set, Gemini CLI will skip automatic detection and attempt
to connect using the provided PID.
### 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]`
@@ -210,7 +280,7 @@ to connect using the provided PID.
- **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]`
@@ -220,9 +290,14 @@ to connect using the provided PID.
IDE, like Antigravity or VS Code.
- **Message:**
`No installer is available for IDE. Please install the Gemini CLI Companion extension manually from the marketplace.`
`No installer is available for IDE. Please install Gemini CLI Companion extension manually from the marketplace.`
- **Cause:** You ran `/ide install`, but the CLI does not have an automated
installer for your specific IDE.
- **Solution:** Open your IDE's extension marketplace, search for "Gemini CLI
Companion", and
[install it manually](#3-manual-installation-from-a-marketplace).
### ACP integration errors
For issues related to ACP integration, please refer to the debugging and
telemetry section in the [ACP Mode](../cli/acp-mode.md) documentation.