richfrem/gemini-cli-agent

🎭 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 & Antigravity CLIs

CLI Mapping & Selection Rule

• Antigravity (agy) CLI: Use this for frontier models (such as Gemini 3.5 Flash or higher models).
• Gemini (gemini) CLI: Use this for cheaper, older models (such as Gemini 3 Flash / gemini-3-flash-preview and prior releases) to conserve token budgets.

Antigravity (agy) CLI (Frontier Models)

• Check Path: which agy (commonly installed at /opt/homebrew/bin/agy or on the system PATH).
• Run non-interactively: agy -p "your prompt" or agy --prompt "your prompt".
• Run in Sandbox Mode: agy --sandbox -p "prompt"
• Skip Permissions: agy --dangerously-skip-permissions -p "prompt" (used for headless subagent dispatches).

Legacy Gemini CLI (gemini) (Cheaper Models)

• 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

# Using agy CLI for frontier models
agy -p "hello"

# Using gemini CLI for cheaper models
gemini -p "hello"