Overview
The Gemini bridge wraps thegemini CLI (from @google/gemini-cli), Google’s terminal-based coding agent. Gemini CLI supports model aliases, approval modes (default, auto_edit, yolo, plan), sandbox isolation, extensions, MCP servers, policy files, session management, and stream-json event streaming. It provides token usage data including cached token counts.
The bridge is implemented by GeminiBridge and configured through GeminiBridgeBuilder. Access the builder through the AgentCtrl facade:
Prerequisites
Install Gemini CLI globally:Basic Usage
Model Selection
Gemini CLI supports model aliases and full model names:Approval Modes
Gemini CLI supports four approval modes that control how tool execution is approved:Sandbox Mode
Enable sandboxed execution for process isolation:sandbox-exec). Docker, Podman, and gVisor are also supported.
System Prompt
Gemini CLI reads instructions from aGEMINI.md file in the project root (similar to CLAUDE.md). You can also set the GEMINI_SYSTEM_MD environment variable to point to a custom system prompt file.
Include Directories
Add additional workspace directories for the agent to access:Extensions
Use specific extensions:MCP Servers
Restrict which MCP servers are available:Policy Files
Load additional policy files for fine-grained tool approval rules:Allowed Tools
Restrict which tools the agent can use:Debug Mode
Enable debug output for troubleshooting CLI behavior:Streaming with Gemini
Gemini streams output as JSONL with thestream-json format. The bridge normalizes these into the standard callback API:
Event Normalization
Gemini emits stream-json events that are normalized:message(role=assistant, delta=true) — Text deltas delivered throughonText().tool_result— Tool results delivered throughonToolUse()with tool name, input (from pairedtool_useevent), result, and error status.error— Errors delivered throughonError()with severity and message.init,tool_use,result— Lifecycle events available through thewiretap()event system.
Session Management
Gemini CLI maintains session history. Agent-Ctrl extracts session IDs from theinit event:
Usage Data
Gemini provides token usage data from theresult event stats: