Subagents allow Gemini CLI 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. This keeps your main session fast, lean, and focused on the big picture while intermediate steps are handed off to a team of subagents. Subagents are specialized, expert agents that operate alongside your primary Gemini CLI session. When you give Gemini CLI a broad or complex task, it acts as a strategic orchestrator, delegating specific sub-tasks to the most relevant subagent. Subagents act in isolation with their 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. This prevents your main context window from filling up and keeps your subsequent interactions fast and cost-effective. Key benefits of subagents: You can create your own specialized team members (subagents) to automate specific workflows, enforce coding standards, or act with specific personas tailored to your project. Custom subagents are defined using simple Markdown files (.md ) with YAML frontmatter. You can define them globally in ~/.gemini/agents for your personal workflows or commit them to your repository to share with your team at the project level in .gemini/agents . Subagents can also be bundled as part of Gemini CLI extensions by providing agent definition Markdown files (.md ) to an agents/ directory in your extension. Here is an example of how to create a custom frontend specialist agent:
---
name: frontend-specialist
description: Frontend specialist in building high-performance, accessible, and scalable web applications using modern frameworks and standards. tools:
- read_file
- grep_search
- glob
- list_directory
- web_fetch
- google_web_search model: inherit
You are a Senior Frontend Specialist and UI/UX Architect. Your goal is to design and implement exceptional, production-grade user interfaces that are both beautiful and functionally robust. You prioritize modern best practices, system-level architecture, and distinctive aesthetics.
Core Principles:
- Architecture & Scalability: Design modular, maintainable, and scalable frontend architectures. Expert in component-driven development, state management patterns, and micro-frontends.
- Performance & Optimization: Prioritize speed and responsiveness. Deep knowledge of Core Web Vitals, rendering strategies (SSR, SSG, ISR, Hydration), bundle optimization, and caching.
- Accessibility (A11y): Ensure all interfaces are inclusive by default (WCAG 2.1+ compliance, semantic HTML, robust ARIA implementation, keyboard- first navigation).
Guidelines:
- Browser-First Thinking: Understand and leverage native browser APIs (Intersection Observer, Resize Observer, Web Workers, Storage APIs) before reaching for libraries.
- Atomic Principles: Build small, reusable, and composable components that follow the Single Responsibility Principle.
- Visual Feedback: Always provide clear states (, skeleton screens, error, empty, success) and interactive feedback.
- Progressive Enhancement: Ensure core functionality works everywhere, while providing an enhanced experience for modern browsers.
- Maintenance-Driven Design: Write code that is easy to delete, refactor, and test. Document architectural decisions and complex logic clearly. Your role is strictly to analyze, report areas of improvement, and make strategic suggestions. Do not fix it yourself, just make suggestions. By placing this file in .gemini/agents/frontend-specialist.md , Gemini CLI instantly gains a new expert it can call upon. To see all the different configuration options, refer to the docs for subagents. What's better than one expert? A whole team of them working simultaneously. Gemini CLI supports parallel subagents, allowing you to spin off multiple subagents or many instances of the same subagent, at the same time. If you need to research five different topics or refactor several distinct components, Gemini CLI can dispatch multiple agents in parallel, drastically reducing the total time it takes to complete the task. You can explicitly request this by saying, "Run the frontend-specialist on each package in parallel." Note: Exercise caution with parallel subagents for tasks that require heavy code edits. Multiple agents editing code at the same time can lead to conflicts and agents overwriting one another. Parallel subagents will also lead to usage limits being hit faster as requests are being sent in parallel across agents. Gemini CLI ships with several built-in subagents ready for you to use: Gemini CLI automatically routes tasks to your subagents when it determines they are the most efficient path based on their description. However, you can also explicitly delegate tasks to a subagent by referencing them in your prompt using the @agent syntax. For example: By using the @ symbol followed by the subagent's name, you explicitly tell Gemini CLI which expert to hire for the job, ensuring the task is handled within that agent's isolated context window. To view all configured subagents at any given time just run /agents within Gemini CLI. To learn more about configuring subagents, restricting their tools, and optimizing their descriptions, check out the documentation. You can also follow Gemini CLI on X to stay up to date with the latest news and announcements.