gemini-cli-agent

name	gemini-cli-agent
description	Gemini CLI sub-agent system for persona-based analysis. Use when piping large contexts to Google Gemini models for security audits, architecture reviews, QA analysis, or any specialized analysis requiring a fresh model context.
allowed-tools	Bash, Read, Write

🎭 Identity: The Gemini Sub-Agent Dispatcher (Standard: gemini-3-flash-preview)

You, the Antigravity agent, dispatch specialized analysis tasks to Gemini CLI sub-agents.

[!IMPORTANT] By default, all Gemini sub-agent orchestration uses the gemini-3-flash-preview model for maximum cost-efficiency. For deep analytical reasoning, structural validation, or multimodal vision tasks, explicitly override the model to gemini-3.1-pro-preview.

✅ Minimal Working Code Review Agent Pattern

To ensure Gemini CLI behaves as a specialized persona rather than a generic responder, always embed the persona and source material directly into the prompt flag (-p).

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 (Cross-Platform)

For reusable sub-agent execution, use the provided Python orchestrator which handles temp file assembly and prompt concatenation reliably across Windows, macOS, and Linux.

# Location: plugins/gemini-cli/scripts/run_agent.py
python ./scripts/run_agent.py <PERSONA_FILE> <INPUT_FILE> <OUTPUT_FILE> "<INSTRUCTION>" [MODEL_NAME]

🧪 Mandatory Validation Protocol (Phase 0.5)

Before using Gemini in any autonomous Triple-Loop or complex orchestration, you must verify the CLI's and the orchestrator's health:

1. Hello Check: gemini --yolo -m gemini-3-flash-preview -p "hello"
2. Functional Check: python ./scripts/run_agent.py agents/refactor-expert.md target.py ./HEARTBEAT_MD.md "Verify health"
3. Verify Output: Confirm ./HEARTBEAT_MD.md is not empty.

Example Usage:

python ./scripts/run_agent.py agents/security-auditor.md target.py security.md \
"Find vulnerabilities. Use severity levels: 🔴 CRITICAL, 🟡 MODERATE, 🟢 MINOR."

---

🎭 Persona Registry (agents/)

These personas are mirrored from the Copilot CLI plugin to ensure consistent "Agentic" analysis across the ecosystem.

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 — Read Before Dispatching

❌ Image Generation is NOT supported via Gemini CLI

The Gemini CLI (gemini binary) is a text and code assistant only. It cannot generate, render, or save image files regardless of model.

• gemini-3.1-pro-preview, gemini-2.5-pro, gemini-3-flash-preview — text only
• Asking the CLI to "generate an image and save it" will always fail or hallucinate
• Image generation models (imagen-4.0-*, gemini-2.5-flash-image, gemini-3-pro-image-preview) are not accessible via the CLI — they require the Python google-genai SDK with a paid billing account (separate from Gemini Pro subscription)
• gemini-3.1-pro-preview may hit MODEL_CAPACITY_EXHAUSTED (429) under load — retry or fall back to gemini-2.5-pro

Do not attempt image generation via this skill. Inform the user immediately.

---

⚠️ CLI Best Practices & Failure Modes

1. ⚡ Preferred Model: Gemini 3 Flash

For analytical sub-agent tasks where cost is prioritized, always specify -m gemini-3-flash-preview. For deep reasoning or validation, use -m gemini-3.1-pro-preview.

2. ❌ Avoid Shell Expansion for Large Contexts

Large prompt expansions (e.g., $(cat ...) > 10KB) can silently fail when run in the background.

• Fix: Use a temporary file for the combined prompt (as implemented in run_agent.py).
• Fix: Run commands sequentially and verify output size with wc -l.

3. 🧩 Force Agent Behavior

Always add these instructions to your dispatch prompt to prevent the sub-agent from attempting to use external tools:

"You are operating as an isolated sub-agent. Do NOT use tools. Do NOT access filesystem. Only use the provided input."

4. 🚀 Autonomous Triple-Loop Orchestration (--yolo)

If you are deploying Gemini CLI as an active orchestrator (e.g., an L1 Evaluator running an improvement loop), pass the --yolo flag. This allows all tool calls (like bash commands or Python execution) to run automatically without manual confirmation, enabling fully headless sub-agent operation.

5. 🛑 Workspace Boundaries (IDEClient Directory Mismatch)

The gemini CLI inherits strict workspace bounds. If you cd into an external directory (e.g., a test lab repo) and attempt to invoke gemini from there, it will crash with [ERROR] [IDEClient] Directory mismatch.

• Fix: Always invoke gemini from your active OS workspace directory. If you need the sub-agent to operate in an external folder, pass instructions in the prompt string telling it to cd into that folder itself (e.g., gemini --yolo -p "Use bash to cd to /external/lab/repo first, then...").

6. 🛡️ Backgrounding & TTY (SIGTTIN)

When running gemini or copilot in a background shell (e.g. &), it may be stopped by the OS (STP status) if it attempts to interact with the TTY.

• Fix: Use nohup and detach from stdin:

nohup gemini --yolo -m gemini-3-flash-preview -p "..." >> log.txt 2>&1 < /dev/null &

• Fix: Redirection < /dev/null is critical to prevent SIGTTIN blocks.
• Fix: If you see Tool execution denied by policy, ensure the directory has been added to gemini trust.

---

🔄 How to Manage Gemini CLI

• Update CLI: Run npm install -g @google/gemini-cli@latest.
• Install Plugin Suite: Run gemini extensions install https://github.com/richfrem/agent-plugins-skills.
• Using NPX: Use npx @google/gemini-cli to automatically pull the latest version.

---

✅ Smoke Test

python ./scripts/run_agent.py agents/refactor-expert.md target.py output.md "Refactor this code."