Gemini CLI Integration

GEMINI.md, long-context batch work, and how Aura keeps Gemini in the loop.

Why This Exists

Gemini CLI occupies a specific niche in a mixed-agent team: long-context, batch-shaped work. A million-token window changes how you use an agent. Tasks that would be multi-session with Claude — "read every file in this service and produce a migration plan" — become single-prompt with Gemini. The tradeoff is that Gemini sessions tend to be less interactive and more one-shot, which changes what coordination looks like.

Sentinel's Gemini integration is designed for that asymmetry. It accepts that Gemini will often produce a large diff in a single burst, and it shifts some coordination weight to pre-session planning and post-session verification rather than inline chatter.

Gemini is the agent you send on expeditions. The Sentinel is how you know what it found.

How It Works

Like the Claude and Cursor integrations, the Gemini wiring has three pieces:

GEMINI.md — the protocol file, parallel to CLAUDE.md. Aura ships a canonical version.
An MCP client or fallback CLI. Gemini CLI has native MCP support in recent versions. Older versions use Aura's fallback mode where the agent calls aura CLI commands directly.
The same git hooks that enforce intent and zones regardless of agent identity.

GEMINI.md template

# AURA PROTOCOL — GEMINI CLI

You are Gemini running in Gemini CLI, operating on a repo managed by Aura.
Other AI agents and human developers may be active. You must coordinate.

## SESSION START
- Call `aura_status` first. Note: pending pulls, active zones, unread
  messages.
- Call `aura_live_impacts` — cross-branch alerts.
- If you see `💬 TEAM` or `📨 SENTINEL`, read the inbox before acting.

## PLANNING (large tasks)
- Because your context is large, PREFER to plan in one pass:
  call `aura_plan_discover` with the full goal, then `aura_plan_lock`
  after the user resolves gray areas.
- Consult `aura_memory_read` broadly — pull all entries related to
  the feature area before drafting the plan.

## BEFORE EDITING FILES
- Call `aura_snapshot` per file. Respect BLOCKED zones absolutely.
- For batch edits touching >10 files, announce via `aura_sentinel_send`
  to="team", kind="announce" FIRST.

## BATCH EDITS
- Log intent ONCE per logical change, not per file. Aggregated intent
  is preferable to per-file chatter for your style of work.
- Call `aura_pr_review` on completion of each logical wave.

## NEVER
- Produce a multi-file diff without prior `aura_snapshot` calls.
- Skip `aura_log_intent` — hook will block commits.
- Ignore impact alerts from `aura_live_impacts`.

The protocol is tuned for Gemini's batch shape. It does not ask Gemini to do per-edit snapshots in a narrow inline loop the way .cursorrules does; instead it asks for a round of snapshots at the start of a wave, followed by the edits, followed by aggregated intent logging.

MCP setup

Modern Gemini CLI exposes MCP via its --tools flag or a settings file:

{
  "mcp": {
    "servers": {
      "aura-vcs": {
        "command": "aura",
        "args": ["mcp", "serve"]
      }
    }
  }
}

For Gemini CLI versions without MCP support, Aura provides a shim that translates tool calls into CLI invocations:

aura gemini shim install

The shim writes a small wrapper to ~/.aura/shims/gemini/ and configures the Gemini CLI extension system to load it. From Gemini's perspective, aura_status, aura_snapshot, aura_log_intent, etc. look like native tools.

Intent logging from Gemini

Because Gemini often produces large diffs in one shot, intent logging is aggregated. A single call looks like:

aura_log_intent
  summary: "Migrate src/legacy/** from Flask to FastAPI"
  files: ["src/legacy/auth.py", "src/legacy/users.py", ...]
  wave: "migration-1"

The hook accepts aggregated intents and validates them against the full diff, not file-by-file. If one of the edited files in the batch doesn't match the intent, the hook surfaces that specific file in the error.

Examples

A classic Gemini expedition

User: Read all of src/legacy/ and produce a FastAPI migration plan,
      then execute wave 1.

[Gemini] → aura_status
[Gemini] → aura_live_impacts
         ← no alerts
[Gemini] → aura_memory_read query="fastapi migration"
         ← k_01HV..: "Preserve existing JWT middleware. See issue-112."
[Gemini] → aura_plan_discover goal="Migrate src/legacy from Flask to FastAPI"
         ← 6 gray areas
User: (resolves gray areas)
[Gemini] → aura_plan_lock
[Gemini] → aura_sentinel_send to="team" kind="announce"
            body="Starting Flask→FastAPI migration wave 1. Will claim
                  zone src/legacy/** block for 2h."
[Gemini] → aura_zone_claim path="src/legacy/**" mode=block ttl=2h
[Gemini] → aura_snapshot on each file in src/legacy/ (bulk)
[Gemini] (produces 40-file diff in one pass)
[Gemini] → aura_log_intent (aggregated)
[Gemini] → aura_pr_review --base main
[Gemini] → aura_zone_release
         → commits via user's git client, hook verifies, passes

One prompt, one expedition, one intent, one commit. Forty files. The Sentinel made sure nobody else was in the way and that the change is auditable after the fact.

Coordinating with a live Claude session

Suppose Claude is actively refactoring src/auth/ while Gemini is asked to do the Flask-to-FastAPI migration. The announcement step is where Sentinel earns its keep:

[Gemini] → aura_sentinel_send to="team" kind="announce"
            body="Starting legacy migration, will claim src/legacy/**"

[Claude] ← inbox banner at next tool call
[Claude] → aura_sentinel_send to="gemini" kind="ack"
            body="Confirmed. src/legacy/ is disjoint from my work. Proceed."

Both agents now have written confirmation of non-interference, and the human team has the full exchange in the dashboard.

Orchestration with aura_gemini_* helpers

Aura ships a set of Gemini-specific tools that are not strictly about Sentinel but often appear alongside it:

aura_gemini_read — read a set of files through Gemini with Aura's context budgeting.
aura_gemini_skim — a token-efficient scan of a large file tree.
aura_gemini_batch — orchestrate a batch of read-only Gemini queries inside a session.

These exist because Gemini's long context is most useful when fed the right shape of input, and Aura has strong opinions about that shape (AST-indexed, node-scoped, knowledge-enriched).

Configuration

[gemini]
geminimd_path = "GEMINI.md"
enforce_presence = true
geminimd_version = "v0.12.6"

[gemini.mcp]
transport = "stdio"
tool_timeout = "60s"    # longer — Gemini batches are slower

[gemini.intent]
aggregate_window = "5m"         # longer than Cursor
per_wave_review = true          # run aura_pr_review per wave

per_wave_review = true is specific to Gemini's batch shape. Because a wave can be dozens of files, automated review after each wave catches issues before they compound across the next wave.

Feature Matrix

| Feature | Gemini CLI Support | Notes | | --- | --- | --- | | MCP client | Full (recent) / Shim (older) | Shim covers versions without native MCP | | Instruction file | GEMINI.md | Canonical template in Aura repo | | Pre-commit hook | Yes | Same hook as Claude/Cursor | | Batch edits | Optimized | Aggregated intent logging | | Sentinel inbox | Full | Read/respond | | Zone claims | Full | Recommended to claim before batch edits | | Knowledge base | Full | Especially useful given long context | | Handover | Less relevant | 1M context makes handover rare | | Plan tools | Full | Single-pass planning fits Gemini's shape |

Limitations

Honesty: the Gemini integration has a few rough edges.

Streaming. MCP over streaming responses is still catching up across Gemini CLI versions. Some Sentinel events are delivered at the end of a tool call rather than inline.
Agent identity. Gemini CLI does not expose a stable session id by default. Aura generates one on shim install, persisted per machine. Multi-machine Gemini setups should verify session ids are unique.
Tool count ceiling. Older Gemini CLI versions cap the exposed MCP tool count at around twenty. Aura provides a --slim server mode that exposes the fourteen most critical tools for those environments:

aura mcp serve --slim

The slim set prioritizes aura_status, aura_snapshot, aura_log_intent, the Sentinel tools, impact tools, knowledge tools, and plan tools. Everything else is reachable by calling the aura CLI directly from the agent.

Why It Matters

Gemini's shape is different enough from Claude's that a single-vendor coordination story would have to pick one. Sentinel picks both. A team that uses Gemini for the big batch work and Claude for the interactive work can have those two agents coordinate through the same inbox, the same zones, the same knowledge base, without either of them noticing that the other is a different model.

That is the whole point of agent-agnosticism. The agents don't have to know about each other. They just have to speak to Sentinel.

Long Context and Knowledge

Gemini's context window changes the cost model for knowledge queries. With Claude or Cursor, a knowledge query returns the top five to ten entries and the agent triages. With Gemini, it is often cheaper to return every remotely relevant entry and let the model filter internally. The aura_memory_read tool accepts a limit parameter; the Gemini protocol file suggests larger limits than the Claude one.

The inverse is also true: Gemini is in an especially good position to write knowledge. Having read an entire module in one pass, Gemini sees the shape of the code more completely than an agent working on fragments, and it notices patterns that produce good knowledge entries. The protocol file encourages Gemini to write entries proactively at the end of expeditions.

Session Identity and Audit

Because Gemini sessions are often one-shot and long-lived, their audit trail is especially important. Every tool call Gemini makes is logged with the generated session id, which is stable for the duration of the shim install. When a Gemini expedition produces a diff, the audit trail includes:

The full sequence of tool calls, in order.
The knowledge entries consulted.
The zone claims held and released.
The inbox messages sent and received.
The plan that was locked and executed.

This is what makes Gemini expeditions reviewable. The human looking at a forty-file PR does not have to re-derive what Gemini was thinking; the audit trail is the thinking.

When Not To Use Gemini

The shape of work that fits Gemini is specific. Pattern-matching against it is useful for team decisions.

Good fits:

Migrations across a module or service.
Bulk renames and signature changes.
Reading a large codebase to produce a plan or summary.
Generating test scaffolding from existing code.

Bad fits:

Interactive bug fixing. Gemini's one-shot shape does not suit the conversation rhythm.
Small-scope edits. Overhead exceeds benefit.
Work that needs to pause for human input mid-session. Gemini CLI's session model is less interactive than Claude Code's.

Teams that use all four agents generally reach for Gemini a few times a week, not many times a day. That is the right rhythm.