Apr 16, 2026 · 5 min read

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.