Welcome to the final installment of our series. In Part 1, we explored the “Hub-and-Spoke” architecture, and in Part 2, we hardened our subagents with tool isolation. Today, we unlock the true speed of the Specialist Network: Parallel Execution.
The Gemini CLI Subagents Series:
- Part 1 : Introduction
- Part 2 : Tool Isolation and Advanced Governance
- Part 3 : Parallel Orchestration and Scaling (this blog)
In 2026, Gemini CLI has evolved from a linear chatbot into a strategic orchestrator. Instead of waiting for one specialist to finish before starting the next, you can now dispatch a whole team simultaneously. This drastically reduces latency for complex research and multi-file analysis.
The Concept: Parallelism vs. Sequential Chains
Let’s revisit the basics again. The Gemini CLI uses a Hub-and-Spoke architecture. The Main Agent (Manager) acts as the hub, and specialized subagents act as the spokes. When you provide a complex command, the Manager analyzes the task and delegates it to the appropriate specialists.
By default, the Main Agent acts as a sequential manager. Sequential: The Manager calls Agent A, waits for the result, then calls Agent B and so on.
However, for tasks like code reviews or multi-directory audits, running specialists in parallel is probably more suitable. In the diagram below, the Manager (Gemini CLI — Main Agent) dispatches two agents : security-auditor and perf-optimizer at the same time, aggregating their summaries once both complete. A sample depiction is shown below:
Let’s get down to seeing the parallel execution of Subagents. But first, we will need to setup a few files.
Step 1: Project Scaffolding
To see this in action, we need a sample project structure. Run these commands in your terminal to set up a project with just enough “substance” for parallel analysis. Notice that we are creating some folders and a file logic.js which has some code with both peformance issues and some security concerns (API_KEY in plain text).
# Create project structure
mkdir -p my-app/src my-app/tests my-app/docs .gemini/agents
# Create a sample source file with both a security risk and a performance bottleneck
cat <<EOF > my-app/src/logic.js
function processData(items) {
// Performance bottleneck: O(n^2) loop
for (let i = 0; i < items.length; i++) {
for (let j = 0; j < items.length; j++) {
console.log(items[i] + items[j]);
}
}
}
const API_KEY = "sk_live_123456789"; // Hardcoded security risk
EOF
# Create a dummy test and documentation file
touch my-app/tests/logic.test.js
touch my-app/docs/API.md
Step 2: Defining the “Specialist Squad”
Next, we define our specialists. One targets performance, while the other targets security vulnerabilities.
1. The Perf-Optimizer
Create .gemini/agents/perf-optimizer.md:
---
name: perf-optimizer
description: Specialized in identifying algorithmic bottlenecks and inefficient loops.
tools:
- read_file
- grep_search
model: inherit
---
You are a Performance Engineer. Scan the code for inefficient loops
or slow execution patterns. Focus on time complexity issues.
2. The Security-Auditor
Create .gemini/agents/security-auditor.md:
---
name: security-auditor
description: Specialized in finding vulnerabilities and hardcoded credentials.
tools:
- read_file
- grep_search
---
You are a Security Auditor. Search for hardcoded API keys, secrets,
or unsafe coding practices. Report findings clearly.
Launch your Gemini CLI. Because these agents are in your project’s .gemini/agents folder, the CLI identifies them as a "new hire" at startup.
The Orchestration Prompt
You can invoke subagents explicitly using the @ syntax to bypass the main agent's decision-making.
Try this in your CLI:
“I’ve just added a new logic.js module. Perform a code review in parallel: use the @security-auditor to scan for leaks and the @perf-optimizer to check for bottlenecks."
What to Observe:
- UI Delegation: The CLI enters “Sub-task” mode, showing individual icons for each agent.
- Tool Usage: You will see the agents using their respective tools (like read_file and grep_search) in isolation.
- The Context Reset: Once the specialists return their concise summaries, the massive lists of intermediate tool calls are purged from your main loop.
Here is a sample run on my machine:
I will read the contents of my-app/src/logic.js and then delegate the security and performance reviews to the specialized sub-agents in parallel.
✓ ReadFile my-app/src/logic.js
✦ I will now trigger parallel reviews: the security auditor will scan for leaks, and the performance optimizer will analyze for bottlenecks in my-app/src/logic.js.
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 2 Agents Completed (ctrl+o to expand) │
│ ✓ security-auditor · Completed successfully │
│ ✓ perf-optimizer · Completed successfully │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ The parallel code review of my-app/src/logic.js is complete. Here is a summary of the findings from both sub-agents:
🛡️ Security Auditor Findings
* Exposed Secret: A hardcoded API key was found on line 9 (const API_KEY = "sk_live_123456789";). This is a critical leak that should be moved to environment variables or a secret manager.
* DoS Risk: The nested loop could potentially be exploited for a Denial of Service attack if triggered with large, untrusted input arrays.
⚡ Performance Optimizer Findings
* Quadratic Complexity (O(n²)): The processData function contains nested loops, causing performance to degrade exponentially as the input size grows.
* Synchronous I/O Bottleneck: Calling console.log inside the nested loops is extremely slow and will block execution, especially since it runs $n^2$ times.
Recommendations:
1. Remove the hardcoded API_KEY.
2. Optimize or remove the nested loops and the redundant logging inside them.
Hope this helps to understand how you can explicitly invoke subagents in parallel.
Deep Dive: Scaling with the Generalist Agent
While custom subagents have restricted toolsets, the generalist agent is your built-in "heavy lifter". It is a general, all-purpose subagent that inherits all tool access and configurations from the main agent.
Why the Generalist is the “Heavy Lifter”:
- High-Volume Execution: Use it for tasks that require many steps, handle large volumes of info, or produce extensive terminal output.
- Multi-File Modifications: It is ideal for applying refactors or fixing errors across several files at once.
- Action-Oriented Research: It can both search code and run commands simultaneously to find a solution.
- Context Optimization: By delegating these massive tasks, you prevent your main conversation from becoming cluttered or slow.
Executing in Parallel
Let’s see the generalist agent in action.
Try the following prompt:
I need to update the copyright headers. Run the @generalist across my-app/src/, my-app/tests/, and my-app/docs/ simultaneously to add '© 2026' to all files.
A sample in-process execution is shown below:
I will now dispatch three generalist agents in parallel to add the '© 2026' copyright header to all files in my-app/src/, my-app/tests/, and my-app/docs/.
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ Running 3 Agents... (ctrl+o to expand) │
│ ! generalist · Edit my-app/src/logic.js: function processData(items) {... => // © 2026... │
│ ! generalist · WriteFile Writing to my-app/tests/logic.test.js │
│ ! generalist · WriteFile Writing to my-app/docs/API.md │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
Here is the final output (Note that it asks for permission to use the WriteFile tool to write the copyright message in each of the files):
I will now dispatch three generalist agents in parallel to add the '© 2026' copyright header to all files in my-app/src/, my-app/tests/, and my-app/docs/.
╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ≡ 3 Agents Completed (ctrl+o to expand) │
│ ✓ generalist · Completed successfully │
│ ✓ generalist · Completed successfully │
│ ✓ generalist · Completed successfully │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ The '© 2026' copyright headers have been successfully added to all files in the specified directories:
* my-app/src/logic.js: Added // © 2026
* my-app/tests/logic.test.js: Added // © 2026
* my-app/docs/API.md: Added <!-- © 2026 -->
Neat, isn’t it?
Infographic
The key parts of this article are highlighted in this infographic (courtesy NotebookLM):
Summary: The Orchestrator’s Manual
By utilizing subagents, you move away from a single global tool registry toward isolated execution environments.
- Custom Specialists: Best for focused context and personas (e.g., Security, QA, UI).
- Generalist Agent: Best for multi-file edits, running tests, or tasks that generate high volumes of noise.
- Manager Agent: Best for maintaining the project’s big-picture goals and coordinating the spokes.
Resources
- Gemini CLI Docs
- Gemini CLI Subagents
- Gemini CLI Policy Engine
- Blog post announcing Subagents
Mastering Gemini CLI Subagents: Part 3 : Parallel Orchestration & Scaling was originally published in Google Cloud – Community on Medium, where people are continuing the conversation by highlighting and responding to this story.
Source Credit: https://medium.com/google-cloud/mastering-gemini-cli-subagents-part-3-parallel-orchestration-scaling-bdb7fb7c81f2?source=rss—-e52cf94d98af—4
About the Author
