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.

pip install agentfield
npm install -g @google/gemini-cli
gemini auth login       # OAuth, or set GEMINI_API_KEY

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.

from pydantic import BaseModel
from agentfield import Agent, HarnessConfig

class RepoAudit(BaseModel):
    risky_paths: list[str]
    summary: str

app = Agent(
    node_id="auditor",
    harness_config=HarnessConfig(
        provider="gemini",
        model="gemini-2.5-pro",
        max_turns=8,
        max_budget_usd=0.40,
    ),
)

@app.reasoner()
async def audit_repo(repo_path: str) -> dict:
    result = await app.harness(
        "Walk the whole repository and surface paths that handle untrusted input.",
        schema=RepoAudit,
        cwd=repo_path,   # per-call override
    )

    if result.is_error:
        return {"ok": False, "error": result.error_message}

    return {
        "ok": True,
        "audit": result.parsed.model_dump(),
        "cost_usd": result.cost_usd,
        "num_turns": result.num_turns,
    }

Composition pattern — scope-then-execute

Gemini ingests the entire repository and produces a tight plan; smaller harness providers execute the individual pieces in parallel.

plan = await app.harness(
    "Walk this repo and list every file that needs the deprecated API removed.",
    provider="gemini",
    schema=RemovalPlan,
)

if plan.is_error:
    raise RuntimeError(plan.error_message)

# Fan out — each file becomes a focused Codex job.
results = await asyncio.gather(*[
    app.harness(
        f"Remove deprecated calls from {file}.",
        provider="codex",
        permission_mode="auto",
        schema=EditReport,
    )
    for file in plan.parsed.files
])

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 login for OAuth, or set GEMINI_API_KEY in the harness environment.
For Vertex AI routing, follow the @google/gemini-cli configuration.

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.