Gemini CLI subagents have arrived, enabling the platform to delegate complex, repetitive, or high-volume tasks to specialized expert agents. Each subagent operates within its own separate context window, custom system instructions, and curated set of tools, keeping the main session fast and focused.
Subagents are specialized, expert agents that operate alongside a primary Gemini CLI session. When given a broad or complex task, Gemini CLI acts as a strategic orchestrator, delegating specific sub-tasks to the most relevant subagent. Each subagent acts in isolation with its own set of tools, MCP servers, system instructions, and context window. Their entire execution, which might involve dozens of tool calls, file searches, or test runs, is consolidated into a single response back to the main agent.
How Gemini CLI Subagents Work
The architecture prevents the main context window from filling up and keeps subsequent interactions fast and cost-effective. This approach is particularly useful for artificial intelligence workflows that require specialized expertise. Subagents return summaries or formatted responses, avoiding context pollution in the primary agent’s session.
Key benefits include keeping the primary agent focused on overall goals and decision-making, speeding up work by running specialized subagents in parallel for research and code exploration, and preventing context rot through isolated execution environments.
Creating Custom Subagents
Developers can create their own specialized team members to automate specific workflows, enforce coding standards, or act with specific personas tailored to their projects. Custom subagents are defined using simple Markdown files with YAML frontmatter. They can be defined globally in ~/.gemini/agents for personal workflows or committed to a repository to share with teams at the project level in .gemini/agents.
Subagents can also be bundled as part of Gemini CLI extensions by providing agent definition Markdown files to an agents/ directory in the extension. For example, a frontend specialist agent can be configured with specific tools like read_file, grep_search, glob, list_directory, web_fetch, and google_web_search, with custom system instructions defining its role and responsibilities.
Parallel Execution Capabilities
Gemini CLI supports parallel subagents, allowing multiple subagents or many instances of the same subagent to run simultaneously. If developers need to research five different topics or refactor several distinct components, Gemini CLI can dispatch multiple agents in parallel, drastically reducing total completion time.
Developers can explicitly request parallel execution by saying, “Run the frontend-specialist on each package in parallel.” However, caution is advised for tasks requiring heavy code edits, as multiple agents editing code simultaneously can lead to conflicts and agents overwriting one another. Parallel subagents also lead to usage limits being hit faster as requests are sent in parallel across agents.
Built-in Subagents and Getting Started
Gemini CLI ships with several built-in subagents ready for immediate use. The generalist agent is a general-purpose agent with access to all tools, perfect for turn-intensive tasks like batch refactoring or running commands with high-volume output. The cli_help agent is an expert on Gemini CLI itself, ready to answer questions about features by having direct access to Gemini CLI documentation.
The codebase_investigator is a specialized agent for exploring codebases, architectural mapping, bug root-cause analysis, and understanding system-wide dependencies. Gemini CLI automatically routes tasks to subagents when it determines they are the most efficient path based on their description. Developers can also explicitly delegate tasks using the @agent syntax, such as “@frontend-specialist Can you review our app and flag potential improvements?” or “@codebase_investigator Map out the authentication flow.”
To view all configured subagents at any time, developers can run /agents within Gemini CLI. Additional configuration options, tool restrictions, and optimization guidance are available in the official documentation and GitHub repository.
