gemini-cli

Gemini CLI (subagent/task delegation)

[!WARNING] DEPRECATED: Gemini CLI has been deprecated in favor of Antigravity CLI (agy). We strongly recommend migrating to /antigravity-cli for up-to-date features (sandbox confinement, /agents dashboard, dynamic status lines, and first-class subagent orchestration). Legacy support for gemini remains available.

Use Gemini CLI to run a separate long-horizon pass over the repo: multi-step implementation, broad refactors, batch file writes, or deep exploration—similar to handing a task to a subagent. You stay orchestrator: smaller prompts, less context burn, often lower spend than doing the same work entirely in-session.

Inside Gemini CLI, subagents are specialists. Prefer @name prefix in the Gemini prompt to force one (e.g. @codebase_investigator Map auth flow). Core specialists include codebase_investigator, generalist, and gemini-cli-security.

When to use Gemini CLI

• Large or multi-step work: several files, phases, or checkpoints (feature slice, migration, test suite, docs sweep).
• Heavy code generation or editing: Gemini drives --yolo tool use while you summarize outcomes and merge.
• Parallel mental lane: you continue planning or reviewing while Gemini runs a bounded task (optionally background—see reference.md).
• Built-in specialists: @codebase_investigator for architecture / dependency mapping; @generalist for heavy multi-file subtasks with isolated context; @gemini-cli-security for security-focused passes.
• Powerful Web Search: Delegate deep research or API documentation searches to Gemini to leverage its integrated Google Search grounding. Use this when the main agent needs up-to-date information not present in the local context.
• Fresh tool stack: Google Search grounding, MCP tools, and other Gemini-only capabilities.
• User explicitly asks for Gemini or “use Gemini for this.”

When not to use

• Small / single-step tasks answerable with one or two edits or a short explanation.
• Tight feedback loops where the user wants rapid back-and-forth refinement in one thread.
• Secrets or policy-sensitive flows—avoid piping credentials; redact before delegating.
• Already-loaded context where duplicating the whole plan adds no value—handle locally.
• Low ROI (Return on Investment): If the task is "needle-in-a-haystack" (requires high precision over a single line) or if the time to compose the Handoff Table exceeds the time to simply edit the file locally. Delegation should only be used when the "mental offloading" outweighs the "handoff overhead."