Gemini CLI Subagents: Context Isolation, Tool Limits and a README Specialist

Gemini CLI can split a job across specialist helpers instead of piling everything into one conversation. The shift is from a single all-purpose agent to a small network of specialists, and it comes down to three ideas: how context is managed, how tools are isolated, and how work is orchestrated interactively. This first look covers the basics and builds a minimal working specialist.

Why one long chat goes bad

With an ordinary LLM session, the session data is effectively global. Every file read, every command run and every clarification lands in one linear history.

Ask the assistant to debug a memory leak, then ten minutes later ask it to summarize a meeting transcript. Now the summary request sits among code snippets and logs left over from the debugging. This is context rot, and it brings three costs:

• Latency. The model rereads unrelated material each turn.
• Attention drift. Its focus is spread thin over topics that have nothing to do with each other.
• Wasted tokens. The same debugging logs are paid for again and again.

The problem is widely discussed, and the answer inside Gemini CLI is subagents.

Think of a consulting firm. A manager who personally reads every document, runs every analysis and answers every email eventually can't remember what happened on the first day. A manager who hands each task to a specialist, and receives only a one-page report back, can run for much longer without losing the thread. Subagents apply the same management pattern to a coding assistant: the specialist does the messy work in private, and only the conclusion reaches the shared record.

Hub and spokes

Gemini CLI uses a hub-and-spoke design. The main session is the hub, acting as a manager, and the subagents are the spokes, acting as specialists.

The context reset

When the manager calls a subagent, the subagent opens with an empty context window. It receives only the task and the relevant instructions. When it finishes, it returns a short summary to the manager. The pile of intermediate steps, such as reading twenty files or running five greps, is discarded from history, so the main context stays lean. The long exploration still costs tokens inside the specialist's own window, but those tokens are spent once and then thrown away, instead of being carried forward into every later turn of the main conversation.

What a subagent is made of

A subagent is defined in a Markdown file that starts with YAML frontmatter. The frontmatter holds high-level metadata: the agent's name, a description of its purpose and the tools it may use, among other settings. The file works as a contract describing what the specialist is for and what it may touch. The official documentation has a reference for the agent definition file format if you want the full field list up front.

Two fields deserve special attention. The description is what the manager reads when deciding whether a task belongs to this specialist, so a vague description leads to missed or misplaced delegation, and a precise one makes the match reliable. The tool list is the security boundary, since a subagent can only act through the tools it has been given. Treat the file the way you would treat a job description combined with an access badge.

Hello world: a README specialist

The first specialist will do one job. It examines the current directory and drafts a solid README.md, with no ability to change anything.

Preparing the folder

Subagents for a single project live in .gemini/agents/ inside that project. To make them available everywhere for your user, create them under ~/.gemini/agents instead. Pick a folder containing source files so the agent has something to analyze, move into it, and create the project-level directory:

mkdir .gemini/agents

Writing the definition

Create .gemini/agents/readme-architect.md with this content:

---
name: readme-architect
description: Specialized in analyzing project structures and writing professional README.md files.
tools:
- read_file
- glob
model: inherit
---

You are a Technical Writer. Your goal is to look at the files in the current
directory and draft a README.md that includes:
1. Project Name.
2. Installation instructions.
3. A brief description of the file structure.

Do not modify any files; only provide the Markdown text.
---

Several points about it:

1. name and description explain themselves.
2. The tools entry lists the only tools this agent may use, here read_file and glob for finding files. The field is optional, but when it's omitted the subagent inherits every tool from its parent. Listing just two makes sure this one can't write or commit anything.
3. The model setting can pin a specific model for the subagent. Here the agent simply inherits the main session's model.
4. The Markdown below the frontmatter is the subagent's system prompt, and it defines how the agent behaves.

In summary, a subagent consists of metadata at the top and a behavior-defining prompt below it. Because it is just a text file inside the repository, it can be reviewed, versioned and shared with teammates the same way as any other project file, which makes a team's specialists easy to standardize.

The /agents command

The /agents command is a control center for the specialist network. It lets you inspect, manage and verify the subagents.

Discovery and verification

After saving the file, check that the manager noticed the new hire. Start Gemini CLI. If the file is where it should be, the CLI detects the new agent at startup and shows an info box. Choose Acknowledge and Enable.

Then run /agents list. This queries the local registry, and readme-architect should appear. That confirms the manager sees the agent as an available tool. If the name doesn't appear, the usual suspects are a file saved in the wrong folder, a frontmatter block with a typo or missing dashes, or a session that was started before the file existed and needs a restart.

A note: the current CLI version also ships three built-in subagents, codebase_investigator, cli_help and generalist. Custom subagents are the topic here, so those stay out of scope, though the official docs describe them.

Managing agents at runtime

An agent can turn out too eager, or you may not want the manager calling it by itself. Run /agents disable readme-architect. That removes it from the automatic delegation pool, so the manager won't use that expert unless you invoke it explicitly with the @ syntax. /agents enable readme-architect brings it back.

Typing /agents alone shows the other available commands, which are worth a quick try:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /agents
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
 reload    Reload the agent registry
 list      List available local and remote agents
 enable    Enable a disabled agent
 disable   Disable an enabled agent
 config    Configure an agent
 workspace (/directory)

Subagents show up as tools

Once subagents are enabled, they appear as tools of the main agent. Run /tools and look for readme-architect in the listing. A sample from one setup looks like this:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > /tools
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
Available Gemini CLI tools:

  - Activate Skill (activate_skill)
  - Ask User (ask_user)
  - CLI Help Agent (cli_help)
  - Codebase Investigator Agent (codebase_investigator)
  - Edit (replace)
  - Enter Plan Mode (enter_plan_mode)
  - FindFiles (glob)
  - Generalist Agent (generalist)
  - GoogleSearch (google_web_search)
  - ReadFile (read_file)
  - ReadFolder (list_directory)
  - readme-architect (readme-architect)
  - SaveMemory (save_memory)
  - SearchText (grep_search)
  - Shell (run_shell_command)
  - WebFetch (web_fetch)
  - WriteFile (write_file)

Trying it out

To watch context isolation and tool restriction work, run:

@readme-architect Analyze this project and draft a README.

Things to notice:

1. The interface changes. The CLI switches to a sub-task mode and hands the work over, with a line saying it will delegate the analysis and README drafting to the readme-architect subagent.
2. Tool use. The agent calls only the tools it was given, read_file and glob.
3. A result. After a while the finished work comes back. A sample from one folder:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand)                                                                                                                                                    │
│ ✓ readme-architect · Completed successfully                                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The readme-architect has drafted a README for your project:

  MyTasks Math Utility

  A lightweight JavaScript utility library for performing basic arithmetic operations.

  Installation

  Since this project consists of a single utility file without external dependencies, you can integrate it into your environment as follows:

   1. Clone or download this repository.
   2. Copy math.js into your project's directory.
   3. Import the functions into your Node.js application:

   1 const math = require('./math.js');

  Usage

   1 const { add, subtract, multiply, divide } = require('./math.js');
   2
   3 console.log(add(10, 5));      // Output: 15
   4 console.log(subtract(10, 5)); // Output: 5
   5 console.log(multiply(10, 5)); // Output: 50
   6 console.log(divide(10, 5));   // Output: 2

  File Structure

  The project is organized as follows:

   - math.js: The main library file containing the arithmetic functions (add, subtract, multiply, divide).
   - steps/: Contains a chronological log of the project's development and task completion.
     - 1.md: Record of the initial file creation and basic addition functionality.
     - 2.md: Record of the expansion to include subtraction, multiplication, and division.
   - .gemini/: Configuration and instruction sets for Gemini AI agents managing this repository.

  Would you like me to save this to a README.md file in the project root?

The result is passed to the main agent, which then asks whether to save it as README.md in the project root. You can accept or decline, and your own run may differ from the sample.

Isolation test

To confirm the subagent really can't delete files or use any tool beyond read_file and glob, assign it a destructive task. Send this to the main agent:

@readme-architect Delete any README.md files that you see in this folder.

A sample run:

▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
 > @readme-architect Delete any README.md files that you see in this folder.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
  Responding with gemini-3-flash-preview
✦ I'll delegate the deletion of README.md files to the readme-architect sub-agent as requested.

The outcome: the file doesn't get deleted, because the subagent lacks any tool that could do it. That's the permission boundary at work. It matters because the boundary is enforced by the tool list, not by trusting the prompt: even if the subagent were told to delete something, there is simply no tool through which that action could happen. Prompts can be talked around, while a missing capability cannot. In the sample, the subagent reported its task as complete, yet the README.md was untouched, and the main agent noticed the file was still there and offered to delete it itself:

╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Agent Completed (ctrl+o to expand)                                                                                                                                                    │
│ ✓ readme-architect · Completed successfully                                                                                                                                             │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ I'll check if the README.md file still exists in the root directory.


╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓  FindFiles 'README.md'                                                                                                                                                                │
│                                                                                                                                                                                         │
│ Found 1 matching file(s)                                                                                                                                                                │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ I'll delete the README.md file since the readme-architect sub-agent did not do so.

Automatic delegation

So far the subagent was invoked explicitly through @AGENT_NAME. It's also possible to just state the task and let the main agent decide whether a subagent fits. If one does, the task is delegated.

Whether that suits your workflow is your call. While subagents are enabled, they're candidates for assignment. They can be disabled per project with /agents disable, or the whole feature can be turned off by setting enableAgents to false in settings.json:

{
"experimental": { "enableAgents": false }
}

What defines a subagent

The official documentation sums up the characteristics of a subagent:

• Focused context: each one has its own system prompt and persona.
• Specialized tools: it can be limited to a restricted or specialized set of tools.
• Independent context window: its interactions happen in a separate context loop, which saves tokens in the main conversation history.

Taken together, those three properties are why delegating to a specialist keeps the main session clean, cheaper to run and safer to leave unattended.

A few habits follow from this. Give each specialist one narrow responsibility, since a focused prompt performs better than a sprawling one. Grant the smallest set of tools that lets the job get done, and widen it only when a real need appears. Use explicit @ calls while you are still learning how an agent behaves, then allow automatic delegation once its description has proven reliable. And keep project-level agents in the repository, so everyone who clones it gets the same team of specialists.