Gemini CLI Subagents

What are Gemini CLI Subagents?

Subagents are specialized expert agents that operate alongside your primary Gemini CLI session. When you give Gemini CLI a broad or complex task, the main agent can delegate specific sub-tasks to the most relevant subagent, acting as an orchestrator.

Each subagent runs in isolation with its own separate context window, custom system instructions, and a curated set of tools. Their work—potentially involving many tool calls, searches, or test runs—gets consolidated into a single response returned to the main session.

Key Features

• Delegation to specialized experts: Gemini CLI can break down a large task into sub-tasks and route them to targeted subagents.
• Isolated execution environments: Each subagent runs with its own context window, system instructions, and curated tools, helping keep the main session from becoming crowded.
• Tool-and-context consolidation: Intermediate steps performed by subagents are consolidated into one response for the primary agent.
• Parallel subagent execution: Gemini CLI supports running multiple subagents simultaneously (either different subagents or multiple instances of the same subagent).
• Custom subagent definitions: You can create your own subagents using simple Markdown files with YAML frontmatter.

How to Use Gemini CLI Subagents

1. Create a subagent definition using a Markdown file (.md) with YAML frontmatter that specifies fields such as name, description, tools, and model (as shown in the provided example for a “frontend-specialist”).
2. Add the definition in one of the supported locations:
   • For personal workflows: ~/.gemini/agents
   • For team/project sharing: .gemini/agents
   • For extensions: include agent definition Markdown files in an extension’s agents/ directory.
3. Use Gemini CLI as usual: provide your overall task in the main Gemini CLI session; Gemini CLI can then dispatch subagents to handle relevant sub-tasks.
4. (If needed) run work in parallel: when tasks naturally split into multiple independent research/refactor/testing tracks, Gemini CLI can dispatch multiple subagents at the same time.

Use Cases

• Research across multiple topics: Delegate separate research threads to different subagents and run them in parallel, then receive consolidated outputs back in the main session.
• Refactor multiple components: Split a refactor into distinct component-level tasks and have specialized subagents work on each area without filling the primary context window.
• Code exploration and analysis: Use expert subagents to investigate code sections and return summaries or formatted results while the primary agent maintains decision-making and final synthesis.
• Testing and validation: Offload sequences of test-related steps (which may involve many tool calls) to subagents so the main session remains responsive.
• Workflow-specific automation with custom personas: Create a reusable specialist agent (e.g., a frontend/UI-UX persona) to enforce consistent approach and tool usage for repeated project workflows.

FAQ

How do subagents differ from the main Gemini CLI session? Subagents are specialized expert agents that run alongside your primary session. They operate in isolation with their own context window, system instructions, and tools, and then return consolidated results.

Can Gemini CLI run more than one subagent at a time? Yes. Gemini CLI supports parallel execution, including spawning multiple subagents or multiple instances of the same subagent simultaneously.

How are custom subagents configured? Custom subagents are defined with Markdown files (.md) that include YAML frontmatter. You can place them in ~/.gemini/agents for personal use, .gemini/agents for project-level sharing, or an extension’s agents/ directory.

What happens to the intermediate work subagents perform? Subagents may run many tool calls, file searches, or test runs, but their execution is consolidated into a single response back to the main agent.

Do subagents have their own tools and system instructions? Yes. Each subagent runs with its own curated set of tools and custom system instructions, distinct from the primary session.

Alternatives

• Single-agent prompting without delegation: You can ask Gemini CLI to handle everything in one context. This avoids setup for custom agents but may be more likely to require long prompts or suffer from context growth.
• Manual workflow splitting: You can run separate, independent prompts for each sub-task and then merge the results yourself. This can mimic delegation, but you handle orchestration and consolidation.
• General-purpose multi-agent frameworks: Tool- or framework-based multi-agent approaches can also route tasks to specialized roles, though the workflow and configuration would differ from Gemini CLI’s subagent definitions and isolation model.
• Chat-based agent roles (non-subagent): If your use case is primarily role-based assistance rather than isolated parallel tool execution, you may find simpler role prompting sufficient, with less control over isolation and consolidated sub-work outputs.