Use agentic chat as a pair programmer

Preview

This product or feature is in preview and is available on the Gemini Code Assist insiders channel. This product or feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

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

1. Set up Gemini Code Assist.
2. Set your Gemini Code Assist release channel to the Insiders build:
   1. Open the Command palette (Cmd + Shift + P) and then select Open User Settings JSON.
   2. Add the following line to your user settings JSON:

      "geminicodeassist.updateChannel": "Insiders",

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.

Caution: There isn't an option to undo changes made to resources outside your IDE in agent mode, so be careful where you use it.

To switch to agent mode:

VS Code

1. To open the Gemini Code Assist chat, in the activity bar of your IDE, click spark Gemini Code Assist.
2. Click the Agent toggle to enter agent mode. The toggle is highlighted when toggled to agent mode and grey when in regular chat.
3. 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.

Caution: MCP servers can run arbitrary code with the permissions available to your user account. Make sure you trust the source of any MCP servers you use.

VS Code

Note: You can't use the command palette to install MCP servers for agent mode. You must add MCP servers to your Gemini settings JSON.

1. Install any dependencies required by your MCP server.
2. Open your Gemini settings JSON located in ~/.gemini/settings.json where ~ is your home directory.

3. 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"]
           }
       }
   }
   

4. 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

1. 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.

2. 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 or descriptions: Shows detailed descriptions of each tool.
  • nodesc or nodescriptions: Hides tool descriptions and only shows tool names.
• /memory: Manages the agent's instructional context loaded from GEMINI.md files. Subcommands include the following:
  • show: Displays the full, concatenated content of the current memory loaded from all available GEMINI.md files.
  • refresh: Reloads the memory from all GEMINI.md files in available locations. For information on how GEMINI.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 or descriptions: Shows detailed descriptions of MCP servers and tools.
  • nodesc or nodescriptions: 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.

Warning: The agent has access to your machine's file system and terminal actions as well as any tools you've configured for use. Be extremely careful where and when you automatically allow agent actions.

To automatically allow all agent actions:

1. Open your VS Code user settings JSON file:

   1. Open the Command palette (ctrl/command + Shift + P).
   2. Select Preferences: Open User Settings (JSON).

2. Add the following to your VS Code user settings JSON file:

   //other settings...
   
   "geminicodeassist.agentYoloMode": "true",
   //other settings...
   

3. 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 where WORKSPACE 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.