Google — Gemini CLI
Spawn Google's Gemini CLI from inside agent loops. The long-context worker — whole-repo passes with massive context windows.
Spawn Google's Gemini CLI from inside agent loops. Reach for it when the task wants the whole codebase as context — Gemini's million-token windows let one pass cover what would take several iterations on a smaller model.
Quickstart
Install the gemini CLI and AgentField. Gemini authenticates against your Google AI account; the harness inherits the environment.
Call the harness
Pin Gemini's defaults on the agent so every .harness(...) call inherits the long-context settings. Override cwd per call to point at different repositories.
Composition pattern — scope-then-execute
Gemini ingests the entire repository and produces a tight plan; smaller providers execute the individual pieces in parallel.
Options
| Option | Type | Default | What it does |
|---|---|---|---|
provider | string | required | "gemini" for this provider. |
model | string | "sonnet" (override it) | Any model the gemini CLI accepts — "gemini-2.5-pro", "gemini-2.5-flash", etc. |
gemini_bin | string | "gemini" | Path to the gemini binary if it is not on $PATH. |
cwd | string | working dir | Forwarded so the agent treats it as the repository root. |
max_turns | int | 30 | Hard cap on agent iterations. |
max_budget_usd | float | null | Cost ceiling. |
env | dict | {} | Extra environment variables forwarded to the subprocess. |
system_prompt | string | null | Custom system prompt prepended to the loop. |
schema | model | null | Pydantic class / Zod schema / Go struct. Forces JSON output validated against the schema. |
Authentication
- Run
gemini auth loginfor OAuth, or setGEMINI_API_KEYin the harness environment. - For Vertex AI routing, follow the
@google/gemini-cliconfiguration.
When to choose Gemini
- Whole-repo comprehension — security audits, architecture summaries, dependency mapping.
- Large-context refactors where you need the agent to see the entire surface before deciding.
- Single-pass analysis when iteration cost is high — one expensive call beats ten short ones.
- Multimodal inputs if the workflow needs images or PDFs alongside code.
Pairs well with
- Claude Code — Gemini ingests the repo, Claude makes the surgical edit.
- Codex — Gemini scopes the work, Codex implements each piece in parallel.
- OpenCode — fall back to a self-hosted model when budget caps trip on long-context calls.