Overview
Deprecated: the Gemini CLI bridge is kept for compatibility only. The upstream Google CLI flow is obsolete for this package, so new integrations should use another AgentCtrl backend.The Gemini bridge wraps the
gemini 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: