| name | gemini-cli-agent |
| plugin | cli-agents |
| description | Gemini CLI sub-agent system for cost-efficient analysis using the `gemini` binary. Use when piping large contexts to cheaper Google Gemini models (gemini-3-flash-preview, gemini-3.1-pro-preview) for security audits, architecture reviews, or QA analysis. For frontier models (Gemini 3.5 Flash and above), use agy-cli-agent instead.
|
| allowed-tools | Bash, Read, Write |
[!WARNING]
Gemini CLI consumer access ends June 18, 2026. Free, Pro, and Ultra users lose access on that date. Only enterprise Gemini Code Assist Standard/Enterprise licenses retain the gemini binary. The replacement for consumer users is the Antigravity (agy) CLI — use agy-cli-agent instead.
Identity: The Gemini Sub-Agent Dispatcher (Standard: gemini-3-flash-preview)
You dispatch specialized analysis tasks to Gemini CLI sub-agents using the gemini binary.
[!IMPORTANT]
Default model: gemini-3-flash-preview (cost-efficient). For deep reasoning, use gemini-3.1-pro-preview. For frontier models (Gemini 3.5 Flash+), use agy-cli-agent instead.
Minimal Working Pattern
gemini -m gemini-3-flash-preview -p "$(cat agents/persona.md)
---SOURCE CODE---
$(cat target.py)
---INSTRUCTION---
Perform a full code review. Use severity levels: 🔴 CRITICAL, 🟡 MODERATE, 🟢 MINOR.
You are operating as an isolated sub-agent.
Do NOT use tools. Do NOT access filesystem." > review.md
Orchestration Pattern: run_agent.py
python ./scripts/run_agent.py <PERSONA_FILE> <INPUT_FILE> <OUTPUT_FILE> "<INSTRUCTION>" [MODEL_NAME]
Mandatory Health Check
Before any complex orchestration:
gemini --yolo -m gemini-3-flash-preview -p "hello"python ./scripts/run_agent.py agents/refactor-expert.md target.py ./heartbeat.md "Verify health"- Confirm
./heartbeat.md is not empty.
Example
python ./scripts/run_agent.py agents/security-auditor.md target.py security.md \
"Find vulnerabilities. Use severity levels: 🔴 CRITICAL, 🟡 MODERATE, 🟢 MINOR."
Persona Registry (agents/)
| Persona | Use For |
|---|
security-auditor.md | Red team, vulnerability scanning, threat modeling |
refactor-expert.md | Optimizing code for readability, performance, and DRY |
architect-review.md | Assessing system design, modularity, and complexity |
Capability Boundary
Image Generation NOT supported
The gemini binary is text and code only. Image generation models require the Python google-genai SDK with a paid billing account.
Model Capacity
gemini-3.1-pro-preview may hit MODEL_CAPACITY_EXHAUSTED (429) under load — retry or fall back to gemini-2.5-pro.
CLI Best Practices
Avoid Shell Expansion for Large Contexts
$(cat ...) > 10KB can silently fail in background processes. Use run_agent.py which writes to a temp file.
Autonomous Orchestration (--yolo)
Pass --yolo to allow all tool calls to run without confirmation for headless operation.
Workspace Boundary (IDEClient Directory Mismatch)
Always invoke gemini from your active workspace directory. To operate in an external folder, pass a cd instruction in the prompt itself.
Backgrounding & TTY (SIGTTIN)
nohup gemini --yolo -m gemini-3-flash-preview -p "..." >> log.txt 2>&1 < /dev/null &
< /dev/null is critical to prevent SIGTTIN stops.
Update / Install
npm install -g @google/gemini-cli@latest
npx @google/gemini-cli
Smoke Test
gemini -p "hello"
python ./scripts/run_agent.py agents/refactor-expert.md target.py output.md "Refactor this code."
