This document describes how to configure and use Gemini Code Assist agent mode as a pair programmer in your integrated development environment (IDE).
Agent mode is available in the VS Code IDE.
With agent mode, you can do any of the following and more:
- Ask questions about your code.
- Use context and built-in tools to improve generated content.
- Configure MCP servers to extend the agent's abilities.
- Get solutions to complex tasks with multiple steps.
- Generate code from design documents, issues, and
TODO
comments. - Control the agent behavior by commenting on, editing, and approving plans and tool use during execution.
Limitations
The following limitations apply when using agent mode:
- The agent can't call Gemini Code Assist tools. You must exit agent mode to use these tools.
- The agent can't use code customization. You must exit agent mode to use code customization.
- Projects with multiple roots aren't supported in agent mode. If you use agent mode in a project with multiple root directories, then the agent only has access to the first root directory it encounters.
- Gemini for Google Cloud logs aren't supported in agent mode.
Before you begin
- Set up the edition of Gemini Code Assist you want to use in your IDE:
- Set your Gemini Code Assist release channel to the Insiders
build:
- Open the Command palette (
Cmd
+Shift
+P
) and then select Open User Settings JSON. - Add the following line to your user settings JSON:
"geminicodeassist.updateChannel": "Insiders",
- Open the Command palette (
Use agent mode
In agent mode, you can ask Gemini to complete high-level goals and complex tasks.
To get the most out of agent mode, follow prompting best practices and provide as much detail as possible.
To switch to agent mode:
VS Code
- To open the Gemini Code Assist chat, in the activity bar of your IDE, click spark Gemini Code Assist.
- Click the Agent toggle to enter agent mode. The toggle is highlighted when toggled to agent mode and grey when in regular chat.
- In the Gemini Code Assist chat, enter your prompt.
Gemini gives you a response to your prompt, or requests permission to use a tool.
To stop the agent, click
Stop.To use the standard Gemini Code Assist chat, click
New chat to create a new chat.Gemini Code Assist agent mode is powered by the Gemini CLI.
IntelliJ
This feature isn't supported in Gemini Code Assist for IntelliJ or other JetBrains IDEs.
Configure tools for agent mode
Tools are a broad category of services that an agent can use for context and actions in its response to your prompt. Some example tools are built-in tools like grep and file read or write, local or remote Model Context Protocol (MCP) servers and their executable functions, or bespoke service implementations.
Configure MCP servers
To control which servers are available in agent mode, add them to your Gemini settings JSON according to the server documentation.
VS Code
- Install any dependencies required by your MCP server.
- Open your Gemini settings JSON located in
~/.gemini/settings.json
where~
is your home directory. Add local or remote MCP servers to your Gemini settings JSON according to the server instructions.
The following example adds the remote Cloudflare MCP server, and installs the GitHub and GitLab servers on the local machine.
{ "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_example_personal_access_token12345" } }, "gitlab": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-gitlab" ] }, "cloudflare-observability": { "command": "npx", "args": ["mcp-remote", "https://observability.mcp.cloudflare.com/sse"] }, "cloudflare-bindings": { "command": "npx", "args": ["mcp-remote", "https://bindings.mcp.cloudflare.com/sse"] } } }
Open the command palette and select Developer: Reload Window.
Your configured MCP servers are available for the agent to use in agent mode.
IntelliJ
This feature isn't supported in Gemini Code Assist for IntelliJ or other JetBrains IDEs.
MCP server authentication
For MCP servers that require authentication, you can add them to your Gemini settings JSON.
The following example adds a personal access token for GitHub:
{
//other settings...
"github": {
"command": "/Users/username/code/github-mcp-server/cmd/github-mcp-server/github-mcp-server",
"args": ["stdio"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ACCESS_TOKEN"
}
},
// other settings...
}
Where ACCESS_TOKEN
is the user's access token.
Create a context file
Context allows an agent to generate better responses for a given prompt. Context can be taken from files in your IDE, files in your local system folders, tool responses, and your prompt details. For more information, see Agent mode context.
VS Code
Create a file named
GEMINI.md
in a location that matches the scope you want the context to apply to. The following table details the locations for context files for different scopes:Scope Location All your projects ~/.gemini/GEMINI.md
A specific project Your working directory or any parent directories up to either your project root (identified by a .git
folder) or your home directory.A specific component, module, or sub-section of a project Subdirectories of your working directory. The agent's memory system is created by loading context files from multiple locations. Context from more specific files, like those for specific components or modules, overrides or supplements content from more general context files like the global context file at
~/.gemini/GEMINI.md
.Write any rules, style guide information, or context that you want the agent to use in Markdown and save the file. For more information, see the example context file on GitHub.
IntelliJ
This feature isn't supported in Gemini Code Assist for IntelliJ or other JetBrains IDEs.
Use commands
Slash /
commands let you quickly run commands similar to commands in a
terminal window.
You can use the following Gemini CLI commands in agent mode:
/tools
: Displays a list of tools that are available in your agent mode session. Subcommands include the following:desc
ordescriptions
: Shows detailed descriptions of each tool.nodesc
ornodescriptions
: Hides tool descriptions and only shows tool names.
/memory
: Manages the agent's instructional context loaded fromGEMINI.md
files. Subcommands include the following:show
: Displays the full, concatenated content of the current memory loaded from all availableGEMINI.md
files.refresh
: Reloads the memory from allGEMINI.md
files in available locations. For information on howGEMINI.md
files contribute to the agent's hierarchical memory, see the Gemini CLI Configuration documentation.
/mcp
: Lists configured Model Context Protocol (MCP) servers, their connection status, server details, and available tools. Subcommands include the following:desc
ordescriptions
: Shows detailed descriptions of MCP servers and tools.nodesc
ornodescriptions
: Hides MCP server descriptions and only shows MCP server names.schema
: Shows the full JSON schema for the MCP server's configured parameters.
/stats
: Displays detailed agent mode session statistics and duration.
For more information on Gemini CLI commands, see Gemini CLI Commands. Note that not all Gemini CLI commands are available in agent mode.
Always allow agent actions
You can automatically allow all agent actions.
To automatically allow all agent actions:
Open your VS Code user settings JSON file:
- Open the Command palette (
ctrl
/command
+Shift
+P
). - Select Preferences: Open User Settings (JSON).
- Open the Command palette (
Add the following to your VS Code user settings JSON file:
//other settings... "geminicodeassist.agentYoloMode": "true", //other settings...
Open the command palette and select Developer: Reload Window.
Agent mode uses yolo mode, and won't ask for permission before taking actions when you send it a prompt.
Create Gemini CLI extensions
You can use Gemini CLI extensions to configure and extend Gemini Code Assist agent mode functionality.
The agent looks for extensions in two locations:
WORKSPACE/.gemini/extensions
whereWORKSPACE
is your current workspace.~/.gemini/extensions
where~
is your home directory.
The agent loads 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.
For more information, see Gemini CLI extensions.
Additional prompts
Try out the following prompts with your own information:
- "What does this repository do? Help me understand the architecture."
- "What does this [class/function] do?"
- "Add a feature to this codebase - "[link-or-path-to-codebase]"."
- "Refactor function [A] and [B] to use the common method [C]."
- "Fix the GitHub issue [link-to-github-issue]."
- "Build an application to do [goal] with a UI that lets the user do [task] in the [environment]."
- "Migrate library versions in this repository from [X] to [Y]."
- "Optimize performance of this Go code so that it runs faster."
- "Use [name-of-API] to build out this feature."
- "Implement an algorithm to do [x], [Y], and [Z]."
What's next
- Read the Gemini Code Assist overview.
- Explore some example MCP servers.
- Find more MCP servers on GitHub.
- Send feedback from your IDE.