Isolated execution
Subagents work in their own separate context window, so intermediate steps do not crowd the main Gemini CLI session.
Gemini CLI subagents
Gemini CLI subagents are specialized helper agents for complex or repetitive tasks, keeping the main session focused. Run automatically or on demand.
Subagents for Gemini CLI
Subagents in Gemini CLI are specialized agents that handle complex, repetitive, or high-volume tasks on behalf of a primary CLI session. The feature is designed to let the main agent stay focused on orchestration, decision-making, and the final response while subagents handle narrower work in their own isolated context windows.
According to the announcement, subagents can use their own tools, MCP servers, and system instructions, and their output is consolidated back into the main session. Gemini CLI can dispatch them automatically when it thinks they are the most efficient path, or you can request one explicitly with the `@agent` syntax.
Key features
Specialized instructions and tools
Each subagent can have its own system instructions and curated tool set, including MCP servers, which lets it behave like a specialized expert.
Parallel delegation
Gemini CLI can run multiple subagents at the same time for research, analysis, code exploration, or tests when a task can be split into parts.
Summarized handoff
The main Gemini CLI session consolidates a subagent’s work into a single response, which keeps the primary conversation focused on the larger task.
Custom agent definitions
Users can define custom agents with Markdown files and YAML frontmatter, either for personal workflows, team repositories, or extensions.
Built-in subagents
The CLI includes built-in subagents such as `generalist`, `cli_help`, and `codebase_investigator` for common workflows.
Practical use cases
Break down complex work
Split a broad task into smaller specialist jobs so research, code exploration, analysis, or testing can happen without filling the main session with intermediate steps.
Parallel research and review
Run multiple subagents at once when you need several related investigations completed faster than a single linear pass.
Enforce local standards
Create a project-specific agent that follows your team’s conventions, instructions, or persona for recurring workflows.
Route work to a specialist
Use built-in subagents like `cli_help` or `codebase_investigator` when you want a specialized helper for Gemini CLI questions or repository exploration.
Ship agents with extensions
Package subagent definitions in a Gemini CLI extension so the same agent behavior can travel with a reusable distribution.
Pros and Cons
Pros
- Keeps the primary Gemini CLI session focused by moving narrow work into separate context windows.
- Supports parallel execution for research, analysis, code exploration, and tests.
- Allows custom subagents to be defined with simple Markdown and YAML.
- Can bundle agent definitions into Gemini CLI extensions or project-level repositories for team use.
Cons
- The announcement is light on setup, limits, and pricing details, so readers still need the official Gemini CLI docs for fuller product evaluation.
- Parallel subagents can increase usage faster, which the post notes as a consideration when tasks are split across multiple agents.
FAQ
What are subagents in Gemini CLI?
Gemini CLI uses subagents to delegate complex or repetitive work to specialized agents that run in isolated context windows with their own tools and instructions. The main session stays focused on orchestration and final decisions.
How do you use a subagent in Gemini CLI?
The announcement says subagents can be invoked automatically by Gemini CLI when appropriate, or explicitly with the @agent syntax. You can view configured subagents by running /agents in Gemini CLI.
Can teams create custom subagents?
Yes. The post says custom subagents can be defined with Markdown files and YAML frontmatter, stored globally in ~/.gemini/agents, committed to a project in .gemini/agents, or bundled with Gemini CLI extensions.
What kinds of tasks are subagents meant for?
The post frames subagents as useful for research, code exploration, analysis, tests, and other high-volume tasks, especially when parallel execution can reduce total time.
Quick Facts
- Category
- Developer Tool
- Product
- Gemini CLI subagents
- Platform
- Gemini CLI
- Source domain
- developers.googleblog.com
- Configuration format
- Markdown with YAML frontmatter
- Built-in agents
- generalist, cli_help, codebase_investigator
Gemini CLI subagents Alternatives
AakarDev AI
AakarDev AI helps teams manage AI provider access, project-level setups, logs, and analytics from one dashboard. It supports BYOK workflows and lists providers including OpenAI, Google Gemini, Anthropic, Groq, Mistral AI, and Perplexity AI.
Skills Janitor
Skills Janitor is a GitHub-hosted set of slash commands for auditing, tracking, and cleaning up Claude Code and OpenAI Codex skills.
Benchspan
Benchspan is an AI agent security platform that discovers agents, blocks prompt injection and data exfiltration in real time, and supports pre-launch red teaming. It is aimed at teams running agents in production and includes Python and TypeScript SDKs.
Codex Plugins
Codex Plugins bundle reusable skills, app integrations, and MCP servers into workflows you can install in the Codex app or use from Codex CLI.
Wallie
Wallie is an open-source AI streamer that watches your screen, hears chat, and delivers live commentary in a configurable persona. Runs locally with your own keys.
ClawTick
ClawTick is an AI agent automation platform for scheduling jobs from the CLI, dashboard, or REST API. It is aimed at developers and teams running LangChain, CrewAI, webhook, or custom agent workflows that need monitoring, alerts, and logs.