Gemini Agent

The gemini agent wraps Google’s Gemini CLI (gemini binary) to execute coding tasks within your workflow. It receives a prompt assembled from the phase role and upstream context, runs Gemini against your workspace, and captures the plain text response.

Gemini CLI is Google’s terminal-based AI coding tool with deep understanding of large codebases. As a cliq agent, it operates non-interactively — receiving its full instructions via the assembled prompt and returning results through the handoff envelope.

Sample Phase

- name: implement
  agent: gemini
  role: developer
  depends_on: [architect]

Phase Configuration

The gemini agent supports two phase types:

Phase Type	Description
`standard`	Code generation, implementation, refactoring, documentation
`gate`	Code review, architectural review, quality verdicts

Phase YAML Fields

Field	Type	Required	Description
`name`	`string`	Yes	Unique phase name within the workflow
`type`	`string`	No	`"standard"` (default) or `"gate"`
`agent`	`string`	Yes	Must be `"gemini"`
`role`	`string`	Yes	Role file name (without `.md`) from `.cliq/roles/`
`depends_on`	`string[]`	No	Upstream phases that must complete before this phase runs
`model`	`string`	No	Model override (e.g., `"gemini-2.5-pro"`)

The role field is required — it tells the agent what persona to adopt and what kind of work to perform. Without a role, the agent has no instructions.

The model field is specified directly on the phase YAML, not in settings. This lets you use different models for different phases in the same pipeline.

Gate Behavior

When used as a gate agent, gemini reviews the upstream work and produces a verdict parsed from its output:

Verdict	Meaning
`PASS`	Work meets quality bar — pipeline continues
`ROUTE`	Work needs changes — routes back to a prior phase with feedback
`ESCALATE`	Work requires human intervention — pipeline halts

Settings

Key	Required	Default	Description
`agents.gemini.api_key`	Yes	—	Google API key for the Gemini CLI

Configure via:

echo $GOOGLE_API_KEY | cliq settings agents.gemini.api_key --stdin --global

Output

The gemini agent writes code directly to the workspace and produces a plain text summary of the work performed. It does not produce structured data — its value is in the files it modifies and the explanation it provides.

Unlike the cursor and claude-code agents which produce stream-json NDJSON output, the gemini agent produces plain text that cliq captures directly.

Handoff Structure

{
    "data": null,
    "text": "The agent's natural language response and summary of work performed."
}

The text field is automatically injected into downstream phases’ prompts, giving subsequent agents full context of what was implemented.

Gate Output

When running as a gate phase, the handoff includes the verdict:

{
    "data": null,
    "text": "The migration script handles rollback correctly and the schema changes are backward-compatible. Test coverage looks good. PASS"
}

The orchestrator parses the verdict keyword from the response and routes the pipeline accordingly.

Examples

Example: Gemini for large codebase tasks

Gemini’s large context window makes it well-suited for tasks that span many files.

phases:
    - name: refactor
      agent: gemini
      role: developer
      model: gemini-2.5-pro

    - name: review
      type: gate
      agent: gemini
      role: reviewer
      depends_on: [refactor]

    - name: finalize
      agent: git
      action: create_pr
      depends_on: [review]

Example: Cross-agent pipeline

Use gemini for implementation with a different agent handling the review gate.

phases:
    - name: fetch-spec
      agent: curl
      sources:
          - name: openapi.json
            url: https://api.internal.com/openapi.json

    - name: implement
      agent: gemini
      role: api-developer
      model: gemini-2.5-pro
      depends_on: [fetch-spec]

    - name: review
      type: gate
      agent: claude-code
      role: reviewer
      depends_on: [implement]

Example: Gemini as gate reviewer

Use gemini specifically for review gates while another agent handles implementation.

phases:
    - name: implement
      agent: cursor
      role: developer

    - name: review
      type: gate
      agent: gemini
      role: senior-reviewer
      model: gemini-2.5-pro
      depends_on: [implement]

    - name: deploy
      agent: git
      action: create_pr
      depends_on: [review]

Setup

1. Install Gemini CLI

npm install -g @google/gemini-cli

Verify the binary is available:

gemini --version

2. Configure the API key

echo $GOOGLE_API_KEY | cliq settings agents.gemini.api_key --stdin --global

3. Validate

cliq doctor agent gemini

This checks that the gemini binary is on PATH and the API key is configured.