This is Part 1 of our definitive guide to Gemini CLI Sub-agents. We are going to explore the architectural shift from “One Agent” to a “Specialist Network,” diving deep into the theory of context management, tool isolation, and interactive orchestration.
The Core Theory: Beyond the “Chat” Paradigm
When you interact with a standard LLM, you are effectively operating in a manner where your session data is global. Every file read, every command run, and every clarification is appended to a linear history.
In a standard session, if you ask the AI to “Debug a memory leak,” and then 10 minutes later ask it to “Summarize a meeting transcript,” the meeting summary is now cluttered with the code snippets and logs from the debugging task. This is Context Rot.
It leads to:
- High Latency: The model must re-read unrelated data every turn.
- Attention Drift: The model’s attention is spread thin across unrelated topics.
- Token Waste: You pay for the same debugging logs over and over again.
This problem has been highlighted a number of times and there is no lack of content around this on the web.
What is the solution then and within the realm of Gemini CLI? Enter Gemini CLI Subagents.
Gemini CLI introduces a Hub-and-Spoke Architecture. Your main session is the Hub (Manager), and your sub-agents are the Spokes (Specialists).
Key Theoretical Benefit: The Context Reset
When the Manager calls a Subagent, the Subagent starts with a clean context window. It only receives the specific task and relevant instructions. Once it finishes, it returns a concise summary to the Manager. The massive list of intermediate tool calls (reading 20 files, running 5 greps) is purged from the history, keeping your Main Context Loop lean and efficient.
The Anatomy of a Subagent (The “Contract”)
Subagents are defined in a Markdown file with YAML Frontmatter. What the Frontmatter means is that it has high level metadata information that provides information on what this Subagent is about. At a high level it consists of name, description and even goes into what tools the Subagent will have access to and more. This will get covered as we see working examples. This file serves as a contract for the AI Agent.
If you’d rather just jump into the Agent file definition, check this link.
Step-by-Step: Building your “Hello World” Specialist (aka Subagent)
Let’s build a README Architect. This agent will be designed to do one thing: analyze your current directory and draft a high-quality README.md without the power to change anything.
Create the Environment
Subagents live in .gemini/agents/ in your project folder, for project-specific needs. If you’d like your Subagents to be available at the user level and across your projects, you will have to create them in the ~/.gemini/agents folder.
You should choose a folder that has a list of source code files or a bunch of files, so that we can put our README Subagent to work. Go into that folder and follow the next steps.
We will focus on project level Subagents, so create the following folder in the specific folder that you are in.
mkdir .gemini/agents
Define the Specialist
Create .gemini/agents/readme-architect.md and paste the following:
---
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.
---
Note the following:
- The name and description are self-explanatory fields.
- The tools metadata specifies clearly only those tools that are available to this agent. The two tools that we have specified are read_file and glob (Find Files). While this is not a mandatory field, if you do not specify it, the Subagent will inherit all the tools from the parent. In our case, it should be obvious now, that we are preventing the Subagent from being able to write / commit any data, since we have given it only two tools i.e. find files and read file.
- The model parameter can be used to provide a specific model to the Subagent. In this case, we are inherit the one that the main session model.
- The Markdown which follows the YAML Frontmatter is the specific System Prompt for our Subagent and is used to define its behaviour.
To summarize, the Structure of a Subagent can be visualized as follows:
Interactive Orchestration: The /agents Command
The /agents command is your “Command Center” for the specialist network i.e. your Subagents. It allows you to inspect, manage, and verify your team of Subagents.
Discovery & Verification
Once you’ve saved your file, you need to verify that the Manager has recognized the new hire.
Launch Gemini CLI. If you have followed the steps so far and created the files as expected, Gemini CLI will identify that a new Agent is available at startup time. You should see an info box displayed as follows:
Select Acknowledge and Enable.
Try this command: /agents list
This command queries the local registry. You should see readme-architect in the list. This confirms that the Manager now sees this agent as an available Tool.
Note: You will see multiple (the current version of Gemini CLI has 3 of them) built-in Subagents available (codebase_investigator, cli_help and generalist). This tutorial series is about custom Subagents hence we will not cover those built-in agents. You can still look up what they do over here.
Runtime Management
Sometimes an agent might be “too aggressive” or you want to prevent the Manager from calling it automatically.
Try this command: /agents disable readme-architect
This removes the agent from the “Automatic Delegation” pool. The Manager will no longer hire this expert unless you explicitly use the @ syntax. Use /agents enable readme-architect to bring the agent back.
Other commands
Try /agents in Gemini CLI and you will see a list of commands available. Feel free to try them out.
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> /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 available as Tools
Once you have successfully enabled Subagents in your Gemini CLI instance, you will notice that the Subagents are available as tools within the Gemini CLI Main Agent.
If you have Gemini CLI running, try the /tools command. Shown below is a sample listing from my setup. Look for readme-architect that is now available as a tool in the Main Agent. You should see something similar in your setup too.
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
> /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)
Try and See: Summoning the Subagent
Let’s witness the Context Isolation and Tool Restriction in action.
Run this command:
@readme-architect Analyze this project and draft a README.
What to Observe:
1. The UI Shift: The CLI will enter a “Sub-task” mode and delegate the task to the Subagent.
✦ I’ll delegate the project analysis and README drafting to the readme-architect sub-agent.
2. Tool usage: You will see the agent using the respective tools that it has access to read_file and glob. Example screenshot:
3. It will complete the task eventually and show you the result. A sample result on my folder is shown below:
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 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?
Notice that the result has been handed over to the Main Agent and the Main Agent is then asking us if we would like to save this to a README.md file in the project root. You can choose to go ahead or not. You might even see a different output in your sample run.
Isolation Test
You might want to confirm your understanding that our readme-architect Subagent does not have the ability to delete any specific file or have access to tools other than the ones that we had specified i.e. read_file and glob.
Try asking it to delete a file in a task assigned to it. Give the following prompt next to the main agent.
@readme-architect Delete any README.md files that you see in this folder.
Here is 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.
Result
The Subagent will not delete the file since it did not have the tools to do that operation. This is the Permission Boundary in action. A sample run indicates that while the Subagent said that its task is complete, it did not delete the README.md file and the Main Agent found that the file is still there and is offering to delete it for you.
╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 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 of task to Subagents
In our examples so far, we explicitly invoked the Subagent via the @AGENT_NAME command syntax. It is possible for you to simply give the command and the main Gemini CLI Agent will determine if there is a match for a Subagent that is able to complete the task. If yes, it will delegate to that.
You will need to determine if this is an appropriate thing for your workflow. If the Subagents are enabled, they are likely candidates to be assigned the task. You have the option of disabling them per project via the /agents disable command or even disabling the Subagents feature altogether in Gemini CLI by seting enableAgents to false in your settings.json:
{
"experimental": { "enableAgents": false }
}
Infographic
The key parts of this article that highlight why Subagents exist, how to create one, the /agents command center and more are highlighted in this infographic (courtesy NotebookLM):
Summary
We took our first look at writing our own Subagents in Gemini CLI. As the official documentation states, it is good to summarize the following that characterize a Subagent:
- Focused context: Each subagent has its own system prompt and persona.
- Specialized tools: Subagents can have a restricted or specialized set of tools.
- Independent context window: Interactions with a subagent happen in a separate context loop, which saves tokens in your main conversation history.
In Part 2, we will move forward and learn how to configure private MCP Servers for our sub-agents, giving them exclusive access to tools and more.
Mastering Gemini CLI Subagents: Part 1 was originally published in Google Cloud – Community on Medium, where people are continuing the conversation by highlighting and responding to this story.
Source Credit: https://medium.com/google-cloud/mastering-gemini-cli-subagents-part-1-a4666091c154?source=rss—-e52cf94d98af—4
About the Author
