12 gemini bridge - Instructor for PHP

Overview

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:

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Enum\AgentType;

// Dedicated factory method
$builder = AgentCtrl::gemini();

// Or via the generic factory
$builder = AgentCtrl::make(AgentType::Gemini);
// @doctest id="a26c"

Prerequisites

Install Gemini CLI globally:

# npm
npm install -g @google/gemini-cli

# Homebrew
brew install gemini-cli

# npx (no install)
npx @google/gemini-cli
# @doctest id="8c2b"

Configure authentication (one of):

# Gemini API key
export GEMINI_API_KEY=...

# Google Cloud API key
export GOOGLE_API_KEY=...

# Or authenticate via Google account (free tier)
gemini
# @doctest id="a1e2"

Basic Usage

use Cognesy\AgentCtrl\AgentCtrl;

$response = AgentCtrl::gemini()
    ->execute('Explain the architecture of this project.');

echo $response->text();
// @doctest id="e41d"

With model selection:

$response = AgentCtrl::gemini()
    ->withModel('flash')
    ->execute('Review the test suite.');

echo $response->text();
// @doctest id="0f6c"

Model Selection

Gemini CLI supports model aliases and full model names:

// Model aliases
AgentCtrl::gemini()->withModel('auto');        // Default (gemini-2.5-pro)
AgentCtrl::gemini()->withModel('pro');         // gemini-2.5-pro
AgentCtrl::gemini()->withModel('flash');       // gemini-2.5-flash
AgentCtrl::gemini()->withModel('flash-lite');  // gemini-2.5-flash-lite

// Full model name
AgentCtrl::gemini()->withModel('gemini-2.5-pro');
// @doctest id="fcf1"

Approval Modes

Gemini CLI supports four approval modes that control how tool execution is approved:

use Cognesy\AgentCtrl\Gemini\Domain\Enum\ApprovalMode;

// Default — prompt for approval on each tool use
AgentCtrl::gemini()->withApprovalMode(ApprovalMode::Default);

// Auto-edit — auto-approve edit tools, prompt for others
AgentCtrl::gemini()->withApprovalMode(ApprovalMode::AutoEdit);

// YOLO — auto-approve all tool executions
AgentCtrl::gemini()->yolo();

// Plan — read-only analysis mode
AgentCtrl::gemini()->planMode();
// @doctest id="d4e3"

Sandbox Mode

Enable sandboxed execution for process isolation:

AgentCtrl::gemini()
    ->withSandbox()
    ->execute('Analyze the codebase.');
// @doctest id="2a32"

On macOS, this uses Seatbelt (sandbox-exec). Docker, Podman, and gVisor are also supported.

System Prompt

Gemini CLI reads instructions from a GEMINI.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:

AgentCtrl::gemini()
    ->withIncludeDirectories(['/projects/shared-lib', '/projects/config'])
    ->execute('Check for shared dependencies.');
// @doctest id="d108"

Extensions

Use specific extensions:

AgentCtrl::gemini()
    ->withExtensions(['my-extension'])
    ->execute('...');
// @doctest id="f464"

MCP Servers

Restrict which MCP servers are available:

AgentCtrl::gemini()
    ->withAllowedMcpServers(['filesystem', 'github'])
    ->execute('...');
// @doctest id="5f74"

Policy Files

Load additional policy files for fine-grained tool approval rules:

AgentCtrl::gemini()
    ->withPolicy(['/path/to/policy.yaml'])
    ->execute('...');
// @doctest id="0af4"

Allowed Tools

Restrict which tools the agent can use:

AgentCtrl::gemini()
    ->withAllowedTools(['read_file', 'search_files', 'list_directory'])
    ->execute('Analyze the codebase structure.');
// @doctest id="818d"

Debug Mode

Enable debug output for troubleshooting CLI behavior:

AgentCtrl::gemini()
    ->debug()
    ->execute('Analyze the codebase.');
// @doctest id="cbc0"

Streaming with Gemini

Gemini streams output as JSONL with the stream-json format. The bridge normalizes these into the standard callback API:

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Dto\AgentResponse;

$response = AgentCtrl::gemini()
    ->onText(fn(string $text) => print($text))
    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("\n> [{$tool}]\n"))
    ->onError(fn(string $message, ?string $code) => print("\nError: {$message}\n"))
    ->onComplete(fn(AgentResponse $r) => print("\n--- Done ---\n"))
    ->executeStreaming('Analyze the error handling in this codebase.');
// @doctest id="db18"

Event Normalization

Gemini emits stream-json events that are normalized:

message (role=assistant, delta=true) — Text deltas delivered through onText().
tool_result — Tool results delivered through onToolUse() with tool name, input (from paired tool_use event), result, and error status.
error — Errors delivered through onError() with severity and message.
init, tool_use, result — Lifecycle events available through the wiretap() event system.

Session Management

Gemini CLI maintains session history. Agent-Ctrl extracts session IDs from the init event:

// First execution
$first = AgentCtrl::gemini()->execute('Create an implementation plan.');
$sessionId = $first->sessionId();

// Continue the most recent session
$next = AgentCtrl::gemini()
    ->continueSession()
    ->execute('Begin implementing the plan.');

// Resume a specific session by ID
if ($sessionId !== null) {
    $next = AgentCtrl::gemini()
        ->resumeSession((string) $sessionId)
        ->execute('Continue with the next step.');
}
// @doctest id="72e7"

Usage Data

Gemini provides token usage data from the result event stats:

$response = AgentCtrl::gemini()
    ->withModel('flash')
    ->execute('Analyze the project dependencies.');

$usage = $response->usage();
if ($usage !== null) {
    echo "Input tokens:    {$usage->input}\n";
    echo "Output tokens:   {$usage->output}\n";
    echo "Total tokens:    {$usage->total()}\n";

    if ($usage->cacheRead !== null) {
        echo "Cached tokens:   {$usage->cacheRead}\n";
    }
}
// @doctest id="b638"

Data Availability

Data Point	Available	Notes
Text output	Yes	Extracted from `message` events (role=assistant, delta=true)
Tool calls	Yes	Normalized from `tool_use` + `tool_result` event pairs
Session ID	Yes	Extracted from `init` event
Token usage	Yes	Input, output, cached tokens from `result` stats
Cost	No	Gemini CLI does not expose cost data
Parse diagnostics	Yes	Malformed JSON line counts and samples

Complete Example

use Cognesy\AgentCtrl\AgentCtrl;
use Cognesy\AgentCtrl\Dto\AgentResponse;
use Cognesy\AgentCtrl\Gemini\Domain\Enum\ApprovalMode;

$response = AgentCtrl::gemini()
    ->withModel('pro')
    ->withApprovalMode(ApprovalMode::AutoEdit)
    ->withIncludeDirectories(['/projects/shared'])
    ->withTimeout(300)
    ->inDirectory('/projects/app')
    ->onText(fn(string $text) => print($text))
    ->onToolUse(fn(string $tool, array $input, ?string $output) => print("\n> [{$tool}]\n"))
    ->onComplete(fn(AgentResponse $r) => print("\n--- Complete ---\n"))
    ->executeStreaming('Review the application architecture and suggest improvements.');

if ($response->isSuccess()) {
    echo "\nReview completed successfully.\n";
    echo "Tools used: " . count($response->toolCalls) . "\n";

    $usage = $response->usage();
    if ($usage !== null) {
        echo "Tokens: {$usage->total()} (in: {$usage->input}, out: {$usage->output})\n";
    }
} else {
    echo "\nFailed with exit code: {$response->exitCode}\n";
}
// @doctest id="f223"

Comparison with Other Bridges

Feature	Claude Code	Codex	OpenCode	Pi	Gemini
System prompts	Yes (replace + append)	No	No	Yes (replace + append)	Yes (GEMINI.md file)
Permission modes	Yes (4 levels)	No	No	No	Yes (4 modes)
Turn limits	Yes	No	No	No	Yes (via settings)
Sandbox modes	No	Yes (3 levels)	No	No	Yes (Seatbelt/Docker/Podman/gVisor)
Image input	No	Yes	No	No	No
Thinking levels	No	No	No	Yes (6 levels)	No
Named agents	No	No	Yes	No	No
File attachments	No	No	Yes	Yes (@-prefix)	No
Extensions	No	No	No	Yes (TypeScript)	Yes
Skills	No	No	No	Yes	No
Tool control	No	No	No	Yes (select/disable)	Yes (allowlist)
MCP servers	No	No	No	No	Yes
Policy engine	No	No	No	No	Yes
Session sharing	No	No	Yes	No	No
Session titles	No	No	Yes	No	No
Ephemeral mode	No	No	No	Yes	No
API key override	No	No	No	Yes	No
Token usage	No	Yes (partial)	Yes (full)	Yes	Yes
Cost tracking	No	No	Yes	Yes	No
Multi-provider models	No	No	Yes	Yes	No
Include directories	No	No	No	No	Yes
Debug mode	No	No	No	No	Yes
Free tier	No	No	No	No	Yes

Environment Variables

Variable	Description
`GEMINI_API_KEY`	Gemini API key
`GOOGLE_API_KEY`	Google Cloud API key
`GOOGLE_APPLICATION_CREDENTIALS`	Service account JSON path
`GOOGLE_CLOUD_PROJECT`	Project ID for Code Assist
`GOOGLE_GENAI_USE_VERTEXAI`	Enable Vertex AI
`GEMINI_SANDBOX`	Enable sandbox without CLI flag

​Overview

​Prerequisites

​Basic Usage

​Model Selection

​Approval Modes

​Sandbox Mode

​System Prompt

​Include Directories

​Extensions

​MCP Servers

​Policy Files

​Allowed Tools

​Debug Mode

​Streaming with Gemini

​Event Normalization

​Session Management

​Usage Data

​Data Availability

​Complete Example

​Comparison with Other Bridges

​Environment Variables