Use agentic chat as a pair programmer

This document describes how to configure and use Gemini Code Assist agent mode as a pair programmer in your integrated development environment (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

Some features of standard Gemini Code Assist chat might not be available in agent mode or might work differently than they do in standard chat.

Recitation is not available in agent mode. While in agent mode, Gemini doesn't cite sources and you can't disable code suggestions that match cited sources.

Before you begin

VS Code

Set up Gemini Code Assist.

IntelliJ

Set up Gemini Code Assist.

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

Click spark Gemini in the tool window bar. Sign in if prompted to do so.
Select the Agent tab.
Describe the task you want the agent to perform.
As the agent goes through the steps to accomplish the task, you'll have the option to review and approve any changes.
Optional: To automatically approve changes, select settings Agent options and click the checkbox next to Auto-approve changes.

Caution: 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 auto-approve changes.

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.

Control built-in tool use

Agent mode has access to your built-in tools like file search, file read, file write, terminal commands, and more.

VS Code

You can use the coreTools and excludeTools settings to control which tools Gemini has access to in agent mode.

coreTools: Lets you specify a list of tools that you want to be available to the model. You can also specify command-specific restrictions for tools that support it. For example—adding the following to your Gemini settings JSON will only allow the shell ls -l command to be executed:"coreTools": ["ShellTool(ls -l)"].
excludeTools: Lets you specify a list of tools that you don't want to be available to the model. You can also specify command-specific restrictions for tools that support it. For example—adding the following to your Gemini settings JSON will block the use of the rm -rf command: "excludeTools": ["ShellTool(rm -rf)"].

A tool listed in both excludeTools and coreTools is excluded.

To configure the built-in tools available in agent mode, do the following:

Open your Gemini settings JSON located in ~/.gemini/settings.json where ~ is your home directory.
To restrict agent tool use to a list of approved tools, add the following line to your Gemini settings JSON:
```
"coreTools": ["TOOL_NAME_1,TOOL_NAME_2"]
```
Replace TOOL_NAME_1 and TOOL_NAME_2 with the names of the built-in tools you want the agent to have access to.

You can list as many built-in tools as you want. By default all built-in tools are available to the agent.
To restrict agent tool use to specific tool commands, add the following line to your Gemini settings JSON:
```
"coreTools": ["TOOL_NAME(COMMAND)"]
```
Replace the following:
- TOOL_NAME: the name of the built-in tool
- COMMAND: the name of the built-in tool command you want the agent to be able to use.
To exclude a tool from agent use, add the following line to your Gemini settings JSON:
```
"excludeTools": ["TOOL_NAME_1,TOOL_NAME_2"]
```
Replace TOOL_NAME_1 and TOOL_NAME_2 with the names of the built-in tools you want to exclude from agent use.
To exclude a tool command from agent use, add the following line to your Gemini settings JSON:
```
"excludeTools": ["TOOL_NAME(COMMAND)"]
```
Replace the following:
- TOOL_NAME: the name of the built-in tool
- COMMAND: the name of the built-in tool command you want to exclude from agent use.

For more information about the coreTools and excludeTools configuration settings, see the Gemini CLI configuration documentation.

IntelliJ

This feature isn't supported in Gemini Code Assist for IntelliJ or other JetBrains IDEs.

Configure MCP servers

VS Code

To control which servers are available in agent mode, add them to your Gemini settings JSON according to the server documentation.

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.
```
                           } 
```
class="devsite-click-to-copy" translate="no" dir="ltr" is-upgraded syntax="JSON">{ "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 
To control which servers are available in agent mode, add them to a mcp.json
file and place it in the configuration directory
for your IDE.


Install any dependencies required by your MCP server.
Create an mcp.json file in your IDE's
configuration 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"]
        }
    }
}




Your configured MCP servers are available for the agent to use in agent mode.


MCP server authentication

Some MCP servers require authentication. Follow the server documentation to
create any required user tokens.



 VS Code 
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.
 IntelliJ 
For MCP servers that require authentication, you can add them to your
mcp.json file.

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.


The agent includes the information in your context file along with any prompts
you send to it.
 IntelliJ 

Create a file named either GEMINI.md or AGENT.md at the root of your
project.
Write any rules, style guide information, or context that you want the
agent to use in Markdown and save the file.


The agent includes the information in your context file along with any prompts
you send to it. You can also add context by including a file manually with the
@FILENAME syntax where
FILENAME is the name of the file with contextual
information you want to include.

Use commands

Slash / commands let you quickly run commands similar to commands in a
terminal window.

VS Code
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.
/mcp: Lists configured Model Context Protocol (MCP) servers, their
connection status, server details, and available tools.


For more information on Gemini CLI commands, see
Gemini CLI Commands. Note that not all
Gemini CLI commands are available in agent mode.
IntelliJ
This feature isn't supported in Gemini Code Assist for IntelliJ or
other JetBrains IDEs.

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:

VS Code
Use yolo mode to automatically allow all agent actions.
To configure yolo mode:


Open your VS Code user settings JSON file:


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

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.
 IntelliJ 
To automatically approve changes, in the Gemini chat agent tab,
select settings Agent options and then
click the checkbox next to Auto-approve changes.

Agent mode automatically approves all requests, and won't ask for permission
before taking actions when you send it a prompt.

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.

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.

Use agentic chat as a pair programmer Stay organized with collections Save and categorize content based on your preferences.

Limitations

Before you begin

VS Code

IntelliJ

Use agent mode

VS Code

IntelliJ

Configure tools for agent mode

Control built-in tool use

VS Code

IntelliJ

Configure MCP servers

VS Code

IntelliJ

MCP server authentication

VS Code

IntelliJ

Create a context file

VS Code

IntelliJ

Use commands

VS Code

IntelliJ

Always allow agent actions

VS Code

IntelliJ

Additional prompts

What's next

Use agentic chat as a pair programmer