diff --git a/docs/cli/acp-mode.md b/docs/cli/acp-mode.md new file mode 100644 index 0000000000..16ff3b9a15 --- /dev/null +++ b/docs/cli/acp-mode.md @@ -0,0 +1,126 @@ +# ACP Mode + +ACP (Agent Client Protocol) mode is a special operational mode of Gemini CLI +designed for programmatic control, primarily for IDE and other developer tool +integrations. It uses a JSON-RPC protocol over stdio to communicate between +Gemini CLI agent and a client. + +To start Gemini CLI in ACP mode, use the `--acp` flag: + +```bash +gemini --acp +``` + +## 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. + +### Existing integrations using ACP + +The ACP Agent Registry simplifies the distribution and management of +ACP-compatible agents across various IDEs. Gemini CLI is an ACP-compatible agent +and can be found in this registry. + +For more general information about the registry, and how to use it with specific +IDEs like JetBrains and Zed, refer to the +[IDE Integration](../ide-integration/index.md) documentation. + +You can also find more information on the official +[ACP Agent Registry](https://agentclientprotocol.com/get-started/registry) page. + +## Architecture and protocol basics + +ACP mode establishes a client-server relationship between your tool (the client) +and Gemini CLI (the server). + +- **Communication:** The entire communication happens over standard input/output + (stdio) using the JSON-RPC 2.0 protocol. +- **Client's role:** The client is responsible for sending requests (e.g., + prompts) and handling responses and notifications from Gemini CLI. +- **Gemini CLI's role:** In ACP mode, Gemini CLI listens for incoming JSON-RPC + requests, processes them, and sends back responses. + +The core of the ACP implementation can be found in +`packages/cli/src/acp/acpClient.ts`. + +### Extending with MCP + +ACP can be used with the Model Context Protocol (MCP). This lets an ACP client +(like an IDE) expose its own functionality as "tools" that the Gemini model can +use. + +1. The client implements an **MCP server** that advertises its tools. +2. During the ACP `initialize` handshake, the client provides the connection + details for its MCP server. +3. Gemini CLI connects to the MCP server, discovers the available tools, and + makes them available to the AI model. +4. When the model decides to use one of these tools, Gemini CLI sends a tool + call request to the MCP server. + +This mechanism lets for a powerful, two-way integration where the agent can +leverage the IDE's capabilities to perform tasks. The MCP client logic is in +`packages/core/src/tools/mcp-client.ts`. + +## Capabilities and supported methods + +The ACP protocol exposes a number of methods for ACP clients (e.g. IDEs) to +control Gemini CLI. + +### Core methods + +- `initialize`: Establishes the initial connection and lets the client to + register its MCP server. +- `authenticate`: Authenticates the user. +- `newSession`: Starts a new chat session. +- `loadSession`: Loads a previous session. +- `prompt`: Sends a prompt to the agent. +- `cancel`: Cancels an ongoing prompt. + +### Session control + +- `setSessionMode`: Allows changing the approval level for tool calls (e.g., to + `auto-approve`). +- `unstable_setSessionModel`: Changes the model for the current session. + +### File system proxy + +ACP includes a proxied file system service. This means that when the agent needs +to read or write files, it does so through the ACP client. This is a security +feature that ensures the agent only has access to the files that the client (and +by extension, the user) has explicitly allowed. + +## Debugging and telemetry + +You can get insights into the ACP communication and the agent's behavior through +debugging logs and telemetry. + +### Debugging logs + +To enable general debugging logs, start Gemini CLI with the `--debug` flag: + +```bash +gemini --acp --debug +``` + +### Telemetry + +For more detailed telemetry, you can use the following environment variables to +capture telemetry data to a file: + +- `GEMINI_TELEMETRY_ENABLED=true` +- `GEMINI_TELEMETRY_TARGET=local` +- `GEMINI_TELEMETRY_OUTFILE=/path/to/your/log.json` + +This will write a JSON log file containing detailed information about all the +events happening within the agent, including ACP requests and responses. The +integration test `integration-tests/acp-telemetry.test.ts` provides a working +example of how to set this up. diff --git a/docs/ide-integration/index.md b/docs/ide-integration/index.md index 6ff893a684..00b5ad846d 100644 --- a/docs/ide-integration/index.md +++ b/docs/ide-integration/index.md @@ -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. > [!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. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index ec8f74de95..8be2ede444 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -2160,37 +2160,14 @@ You can customize this behavior in your `settings.json` file: Arguments passed directly when running the CLI can override other configurations for that specific session. -- **`--model `** (**`-m `**): - - Specifies the Gemini model to use for this session. - - Example: `npm start -- --model gemini-3-pro-preview` -- **`--prompt `** (**`-p `**): - - **Deprecated:** Use positional arguments instead. - - Used to pass a prompt directly to the command. This invokes Gemini CLI in a - non-interactive mode. -- **`--prompt-interactive `** (**`-i `**): - - Starts an interactive session with the provided prompt as the initial input. - - The prompt is processed within the interactive session, not before it. - - Cannot be used when piping input from stdin. - - Example: `gemini -i "explain this code"` -- **`--output-format `**: - - **Description:** Specifies the format of the CLI output for non-interactive - mode. - - **Values:** - - `text`: (Default) The standard human-readable output. - - `json`: A machine-readable JSON output. - - `stream-json`: A streaming JSON output that emits real-time events. - - **Note:** For structured output and scripting, use the - `--output-format json` or `--output-format stream-json` flag. -- **`--sandbox`** (**`-s`**): - - Enables sandbox mode for this session. -- **`--debug`** (**`-d`**): - - Enables debug mode for this session, providing more verbose output. Open the - debug console with F12 to see the additional logging. - -- **`--help`** (or **`-h`**): - - Displays help information about command-line arguments. -- **`--yolo`**: - - Enables YOLO mode, which automatically approves all tool calls. +- **`--acp`**: + - Starts the agent in Agent Communication Protocol (ACP) mode. +- **`--allowed-mcp-server-names`**: + - A comma-separated list of MCP server names to allow for the session. +- **`--allowed-tools `**: + - A comma-separated list of tool names that will bypass the confirmation + dialog. + - Example: `gemini --allowed-tools "ShellTool(git status)"` - **`--approval-mode `**: - Sets the approval mode for tool calls. Available modes: - `default`: Prompt for approval on each tool call (default behavior) @@ -2204,35 +2181,24 @@ for that specific session. - Cannot be used together with `--yolo`. Use `--approval-mode=yolo` instead of `--yolo` for the new unified approach. - Example: `gemini --approval-mode auto_edit` -- **`--allowed-tools `**: - - A comma-separated list of tool names that will bypass the confirmation - dialog. - - Example: `gemini --allowed-tools "ShellTool(git status)"` -- **`--extensions `** (**`-e `**): - - Specifies a list of extensions to use for the session. If not provided, all - available extensions are used. - - Use the special term `gemini -e none` to disable all extensions. - - Example: `gemini -e my-extension -e my-other-extension` -- **`--list-extensions`** (**`-l`**): - - Lists all available extensions and exits. -- **`--resume [session_id]`** (**`-r [session_id]`**): - - Resume a previous chat session. Use "latest" for the most recent session, - provide a session index number, or provide a full session UUID. - - If no session_id is provided, defaults to "latest". - - Example: `gemini --resume 5` or `gemini --resume latest` or - `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume` - - See [Session Management](../cli/session-management.md) for more details. -- **`--list-sessions`**: - - List all available chat sessions for the current project and exit. - - Shows session indices, dates, message counts, and preview of first user - message. - - Example: `gemini --list-sessions` +- **`--debug`** (**`-d`**): + - Enables debug mode for this session, providing more verbose output. Open the + debug console with F12 to see the additional logging. - **`--delete-session `**: - Delete a specific chat session by its index number or full session UUID. - Use `--list-sessions` first to see available sessions, their indices, and UUIDs. - Example: `gemini --delete-session 3` or `gemini --delete-session a1b2c3d4-e5f6-7890-abcd-ef1234567890` +- **`--extensions `** (**`-e `**): + - Specifies a list of extensions to use for the session. If not provided, all + available extensions are used. + - Use the special term `gemini -e none` to disable all extensions. + - Example: `gemini -e my-extension -e my-other-extension` +- **`--fake-responses`**: + - Path to a file with fake model responses for testing. +- **`--help`** (or **`-h`**): + - Displays help information about command-line arguments. - **`--include-directories `**: - Includes additional directories in the workspace for multi-directory support. @@ -2240,19 +2206,52 @@ for that specific session. - 5 directories can be added at maximum. - Example: `--include-directories /path/to/project1,/path/to/project2` or `--include-directories /path/to/project1 --include-directories /path/to/project2` +- **`--list-extensions`** (**`-l`**): + - Lists all available extensions and exits. +- **`--list-sessions`**: + - List all available chat sessions for the current project and exit. + - Shows session indices, dates, message counts, and preview of first user + message. + - Example: `gemini --list-sessions` +- **`--model `** (**`-m `**): + - Specifies the Gemini model to use for this session. + - Example: `npm start -- --model gemini-3-pro-preview` +- **`--output-format `**: + - **Description:** Specifies the format of the CLI output for non-interactive + mode. + - **Values:** + - `text`: (Default) The standard human-readable output. + - `json`: A machine-readable JSON output. + - `stream-json`: A streaming JSON output that emits real-time events. + - **Note:** For structured output and scripting, use the + `--output-format json` or `--output-format stream-json` flag. +- **`--prompt `** (**`-p `**): + - **Deprecated:** Use positional arguments instead. + - Used to pass a prompt directly to the command. This invokes Gemini CLI in a + non-interactive mode. +- **`--prompt-interactive `** (**`-i `**): + - Starts an interactive session with the provided prompt as the initial input. + - The prompt is processed within the interactive session, not before it. + - Cannot be used when piping input from stdin. + - Example: `gemini -i "explain this code"` +- **`--record-responses`**: + - Path to a file to record model responses for testing. +- **`--resume [session_id]`** (**`-r [session_id]`**): + - Resume a previous chat session. Use "latest" for the most recent session, + provide a session index number, or provide a full session UUID. + - If no session_id is provided, defaults to "latest". + - Example: `gemini --resume 5` or `gemini --resume latest` or + `gemini --resume a1b2c3d4-e5f6-7890-abcd-ef1234567890` or `gemini --resume` + - See [Session Management](../cli/session-management.md) for more details. +- **`--sandbox`** (**`-s`**): + - Enables sandbox mode for this session. - **`--screen-reader`**: - Enables screen reader mode, which adjusts the TUI for better compatibility with screen readers. - **`--version`**: - Displays the version of the CLI. -- **`--experimental-acp`**: - - Starts the agent in ACP mode. -- **`--allowed-mcp-server-names`**: - - Allowed MCP server names. -- **`--fake-responses`**: - - Path to a file with fake model responses for testing. -- **`--record-responses`**: - - Path to a file to record model responses for testing. +- **`--yolo`**: + - Enables YOLO mode, which automatically approves all tool calls. ## Context files (hierarchical instructional context) diff --git a/docs/sidebar.json b/docs/sidebar.json index e1ebd6ddd5..ea82a64481 100644 --- a/docs/sidebar.json +++ b/docs/sidebar.json @@ -111,7 +111,17 @@ { "label": "Reference", "slug": "docs/hooks/reference" } ] }, - { "label": "IDE integration", "slug": "docs/ide-integration" }, + { + "label": "IDE integration", + "collapsed": true, + "items": [ + { "label": "Overview", "slug": "docs/ide-integration" }, + { + "label": "Developer guide: ACP mode", + "slug": "docs/cli/acp-mode" + } + ] + }, { "label": "MCP servers", "slug": "docs/tools/mcp-server" }, { "label": "Model routing", "slug": "docs/cli/model-routing" }, { "label": "Model selection", "slug": "docs/cli/model" },