Apr 16, 2026 · 6 min read

Last updated on Apr 19, 2026

Gemini CLI Subagents: Parallel Task Delegation Guide (2026)

Gemini CLI now supports subagents — specialized AI agents that run in their own context window, with their own tools and system prompts. Instead of cramming everything into one conversation, you delegate specific tasks to focused specialists.

This shipped in April 2026 and mirrors what Claude Code has had with its subagent feature. The key difference: Gemini CLI subagents are fully customizable via Markdown files and support parallel execution out of the box.

What subagents solve

Without subagents, a long coding session accumulates context: file reads, tool outputs, debugging attempts. Eventually the context window fills up and quality degrades — what Anthropic calls “context rot.”

Subagents fix this by running tasks in isolated context windows. The main agent delegates a task, the subagent does the work in its own context, and only the result comes back to the main conversation. All the intermediate steps (file reads, failed attempts, debugging) stay in the subagent’s context and don’t pollute yours.

How to use subagents

Automatic delegation

Gemini CLI automatically delegates to built-in subagents when it recognizes a task that matches a specialist. You don’t need to do anything — the main agent decides when to delegate.

Manual delegation with @ syntax

Force delegation to a specific subagent:

@codebase-investigator What authentication patterns does this project use?

@cli-help How do I configure custom subagents?

@browser-agent Check the Stripe API docs for webhook signature verification

The @agent-name syntax tells Gemini CLI to route the task directly to that subagent instead of handling it in the main context.

Built-in subagents

Gemini CLI ships with four built-in subagents:

Subagent	Purpose	Best for
Codebase Investigator	Deep code analysis	”How does auth work in this project?”
CLI Help Agent	Gemini CLI documentation	”How do I configure settings?”
Generalist Agent	General-purpose tasks	Overflow tasks that don’t fit a specialist
Browser Agent (experimental)	Web browsing and research	”Check the docs for this API endpoint”

The Codebase Investigator is the most useful. It reads through your project files in its own context window, builds understanding, and returns a summary. Your main context stays clean.

Creating custom subagents

Custom subagents are defined as Markdown files in .gemini/agents/:

<!-- .gemini/agents/security-reviewer.md -->
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools:
  - read_file
  - search_files
  - web_search
---

You are a security expert. When given code to review:

1. Check for SQL injection, XSS, CSRF, and authentication issues
2. Check for hardcoded secrets and credentials
3. Check dependency versions for known CVEs
4. Provide specific fix recommendations with code examples

Be thorough but concise. Prioritize critical issues first.

Then use it:

@security-reviewer Review the authentication middleware in src/auth/

Configuration schema

The frontmatter supports:

name: agent-name           # How you invoke it with @
description: What it does  # Shown in /agents list
tools:                     # Restrict available tools
  - read_file
  - edit_file
  - shell
model: gemini-2.5-pro      # Override the model (optional)

Tool wildcards

Use * to give a subagent access to all tools, or restrict to specific ones for security:

# Full access
tools:
  - "*"

# Read-only (safe for analysis tasks)
tools:
  - read_file
  - search_files
  - list_directory

Restricting tools is important for agent security. A code review subagent shouldn’t need shell access.

Parallel execution

Gemini CLI can run multiple subagents simultaneously. When the main agent identifies independent tasks, it delegates them in parallel:

Refactor the auth module and update the API docs at the same time.

Gemini CLI might spawn:

A subagent to refactor src/auth/
A subagent to update docs/api.md

Both run concurrently. Results merge back into the main context when both complete.

You can also force parallel execution:

@codebase-investigator Analyze the database schema
@security-reviewer Check the API endpoints for auth issues

Both subagents start immediately in their own context windows.

Managing subagents

Interactive management

Use /agents in Gemini CLI to see all available subagents, their status, and configuration.

Persistent configuration

Configure subagent behavior in settings.json:

{
  "subagents": {
    "enabled": true,
    "auto_delegate": true,
    "max_parallel": 3,
    "custom_agents_dir": ".gemini/agents"
  }
}

Disabling subagents

If you prefer single-agent mode:

{
  "subagents": {
    "enabled": false
  }
}

Gemini CLI vs Claude Code subagents

Feature	Gemini CLI	Claude Code
Custom agents	✅ Markdown files	❌ Built-in only
Parallel execution	✅ Native	✅ Native
Tool restriction	✅ Per-agent	❌ Same tools as main
@ syntax	✅ `@agent-name`	❌ Natural language delegation
Agent-to-Agent (A2A)	✅ Remote subagents	❌ Not supported
Model override	✅ Per-agent	❌ Same model
Context isolation	✅ Full	✅ Full

Gemini CLI’s advantage is customization. You can create domain-specific agents with restricted tools and even different models. Claude Code’s advantage is simplicity — you just tell it to “spin up a subagent” in natural language.

Practical subagent setups

For a full-stack project

.gemini/agents/
├── frontend-expert.md      # React, CSS, browser APIs
├── backend-expert.md       # API design, database, auth
├── test-writer.md          # Writes and runs tests
└── security-reviewer.md    # Security analysis (read-only tools)

For a monorepo

.gemini/agents/
├── service-a-expert.md     # Knows service A's codebase
├── service-b-expert.md     # Knows service B's codebase
├── infra-expert.md         # Terraform, Docker, CI/CD
└── api-contract-checker.md # Validates API contracts between services

For code review

.gemini/agents/
├── style-checker.md        # Code style and conventions
├── perf-analyzer.md        # Performance analysis
├── security-scanner.md     # Vulnerability detection
└── doc-checker.md          # Documentation completeness

Run all four in parallel on a PR: @style-checker @perf-analyzer @security-scanner @doc-checker Review the changes in this PR.

When to use subagents vs a single agent

Use subagents when:

Tasks are independent and can run in parallel
You need domain expertise (security, performance, specific service)
Your main context is getting long and quality is degrading
You want tool restrictions for safety

Use a single agent when:

Tasks are sequential and depend on each other
The context is short and focused
You need the agent to see the full picture at once

For most real projects, a mix works best. Start in single-agent mode, delegate to subagents when the context gets heavy or when you need parallel work.

FAQ

What are Gemini CLI subagents?

Subagents are specialized AI agents that run in their own isolated context window with their own tools and system prompts. They let you delegate specific tasks (like security review or code analysis) without polluting your main conversation’s context.

Can subagents work in parallel?

Yes, Gemini CLI supports native parallel execution of subagents. When tasks are independent, you can invoke multiple subagents simultaneously with @agent-name syntax and their results merge back into your main context when complete.

Is this feature free?

Gemini CLI subagents use the same Gemini API credits as regular usage. Each subagent consumes tokens in its own context window, so running multiple subagents in parallel will use more tokens than a single-agent approach, but you get faster results and cleaner context.

How do subagents compare to Claude Code agent teams?

Gemini CLI offers more customization — you can create custom agents via Markdown files, restrict tools per agent, and override models. Claude Code’s advantage is simplicity, using natural language delegation without configuration files, but it doesn’t support custom agents or per-agent tool restrictions.