feat: Add support for Google Gemini CLI as an AI Engine

[petermefrandsen]

Is your feature request related to a problem? Please describe.

Currently, the repository supports various AI engines, but it lacks support for Google Gemini.

Gemini (specifically 1.5 Pro and Flash) offers massive context windows and strong reasoning capabilities that are highly beneficial for agentic workflows, particularly when analyzing large codebases or performing complex reasoning tasks.

Describe the solution you'd like

I propose adding gemini-cli as a supported engine provider. The integration should leverage the CLI's headless mode, which is specifically designed for programmatic usage and automation.

Implementation Plan:

1. Execution: Use the headless mode with JSON output to get structured responses suitable for parsing.

   gemini --prompt "Your prompt here" --output-format json

2. Authentication: Support standard Gemini authentication methods. The simplest integration path for CI/CD and headless environments is the API Key:

   • Environment Variable: GEMINI_API_KEY
   • Alternative: Google Cloud Application Default Credentials (ADC) for Vertex AI users.

3. Response Handling: The CLI returns a structured JSON object that the agent can parse. The wrapper needs to handle the following schema:

   {
     "response": "The AI's actual text response...",
     "stats": {
       "models": { ... },
       "tools": { ... }
     }
   }

4. Streaming (Optional but recommended): The CLI also supports streaming JSON events via --output-format stream-json, which could be used to provide real-time feedback in the UI if supported by the architecture.

Describe alternatives you've considered

• Direct API SDK: We could use the Google AI SDK directly (e.g., in Go or Node). However, using the gemini-cli wrapper aligns with the tool-based nature of this repository and provides a unified interface for both Standard Gemini and Vertex AI without extra configuration.

Additional context

Documentation References:

• Gemini CLI Installation
• Authentication Guide
• Headless Mode & JSON Output

[pelikhan]

Does gemini support LLM gateways?

[petermefrandsen]

Does gemini support LLM gateways?

Yes. The Google Gemini CLI natively supports LLM gateways and corporate proxies by allowing users to override the API base URL.

Example

The Gemini CLI respects the GOOGLE_GEMINI_BASE_URL environment variable. By setting this, all traffic, including prompts, file context, and tool execution results, is redirected from Google's public endpoints to the custom gateway.

Example Configuration:

# Redirect CLI traffic to a local or corporate gateway (e.g., LiteLLM or Kong)
export GOOGLE_GEMINI_BASE_URL="[https://your-internal-gateway.com/v1](https://your-internal-gateway.com/v1)"
export GEMINI_API_KEY="your-gateway-token"

# The CLI now communicates exclusively through the gateway
gemini --prompt "Review this code for security vulnerabilities"

References

• LiteLLM Documentation: They have a dedicated tutorial titled "Using Gemini CLI Through LiteLLM Proxy". It explicitly instructs users to set GOOGLE_GEMINI_BASE_URL to the proxy address.
• There is an active GitHub Issue (#15543) in the official google-gemini/gemini-cli repo specifically discussing and requesting more explicit documentation for these custom LLM gateways.

[pelikhan]

We need to be able to gateway out of the agent container back into the gemini endpoints.

[pelikhan]

/scout do a research on Gemini-cli to gather information about implementing it as an agentic engine in AW.

• headless execution
• authentication
• LLM gateway support
• connection to Google Gemini endpoints directly from the gateway

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report: Gemini-CLI as an Agentic Engine in AW

Triggered by @pelikhan

Executive Summary

Gemini-CLI is a production-ready, open-source AI agent that uses a ReAct (Reason and Act) loop architecture and is highly suitable for integration as an agentic engine in AW. Key findings:

• ✅ Headless execution: Robust support with JSON output, stdin/stdout piping, and scriptability
• ✅ Authentication: Multiple methods including API keys, Vertex AI, OAuth, and ADC
• ✅ LLM Gateway support: Confirmed integration with Kong AI Gateway, LiteLLM Proxy, and custom proxies via GOOGLE_GEMINI_BASE_URL
• ✅ Direct Gemini endpoints: Supports both AI Studio API and Vertex AI endpoints with flexible authentication
• ⚠️ Agentic architecture: Uses ReAct loop with MCP (Model Context Protocol) for extensible tool integration

View Detailed Research Findings

1. Headless Execution Capabilities

Core Features

Gemini-CLI provides comprehensive headless mode support:

# Basic headless usage
gemini -p "Your prompt here"

# With JSON output for parsing
gemini -p "Your prompt" --output-format json

# Stdin piping
cat file.txt | gemini -p "Summarize this"

# Auto-approval mode (no user interaction)
gemini -p "Your prompt" --yolo

Key Command-Line Options

Option	Purpose	Example
--prompt, -p	Run in headless mode	gemini -p "query"
--output-format	Specify output (text/json)	--output-format json
--model, -m	Specify Gemini model	-m gemini-2.5-flash
--yolo, -y	Auto-approve all actions	--yolo
--approval-mode	Set approval mode	--approval-mode auto_edit
--all-files, -a	Include all files in context	--all-files

Use Cases

• CI/CD pipelines for automated code reviews
• Batch processing and automation scripts
• Cron jobs for scheduled AI tasks
• Integration with other CLI tools via pipes

Performance Note: Current initialization can take 30-60 seconds due to MCP server loading. There's an open feature request (#18124) for optimized "fast-track" mode for one-off commands.

Source: [Official Headless Mode Documentation]((googlegemini.github.io/redacted)

---

2. Authentication Methods

Gemini-CLI supports multiple authentication approaches suitable for different deployment scenarios:

Method 1: Gemini API Key (Simplest)

# Set environment variable
export GEMINI_API_KEY="your-api-key-here"

# Or use .env file
echo 'GEMINI_API_KEY="your-api-key"' >> ~/.gemini/.env

# Run headless
gemini -p "Your query"

• Best for: Development, testing, pay-as-you-go usage
• Rate limits: Free tier provides 60 requests/min, 1,000 requests/day
• Obtain key from: [Google AI Studio]((aistudio.google.com/redacted)

Method 2: Vertex AI with API Key

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_API_KEY="your-google-api-key"
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

• Best for: Enterprise deployments with GCP integration
• Features: Higher quotas, monitoring, provisioned throughput

Method 3: Application Default Credentials (ADC)

# Authenticate with gcloud
gcloud auth application-default login

export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"

• Best for: Headless servers, CI/CD, production environments
• Benefits: No API keys in code, automatic credential rotation

Method 4: Service Account (Production)

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_CLOUD_PROJECT="your-project-id"

• Best for: Production deployments, containerized environments
• Benefits: Fine-grained IAM control, audit logging

Headless Server Authentication

For SSH/headless scenarios:

# Option 1: No-launch browser mode
gcloud auth login --no-launch-browser

# Option 2: SSH port forwarding for OAuth
ssh -L 8080:localhost:8080 your-server
# Complete OAuth in local browser, token saves on remote server

Security Best Practice: Store credentials in .gemini/.env (project-specific) or ~/.gemini/.env (user-wide), not in shell config files.

Source: [Authentication Guide]((googlegemini.github.io/redacted)

---

3. LLM Gateway Support

Gemini-CLI has confirmed support for LLM gateway proxies, which is critical for enterprise deployments.

Supported Gateway Solutions

Kong AI Gateway (Production-Ready)

# Configure AI Proxy plugin for Gemini
export GOOGLE_GEMINI_BASE_URL="(yourkonggateway.com/redacted)
export GEMINI_API_KEY="gateway-api-key"

# Kong routes traffic to Gemini API
# Provides: rate limiting, authentication, caching, observability

Benefits:

• Centralized authentication management
• Request logging and monitoring
• Load balancing across multiple AI providers
• Cost tracking and usage quotas
• Guardrails and content filtering

Tutorial: [Route Gemini CLI through Kong AI Gateway]((developer.konghq.com/redacted)

LiteLLM Proxy (Open Source)

# Configure Gemini CLI to use LiteLLM proxy
export GOOGLE_GENAI_USE_VERTEXAI=true
export GOOGLE_GEMINI_BASE_URL="(localhost/redacted)
export GEMINI_API_KEY="litellm-virtual-key"

Critical Note: When using Google Login authentication (option 1), Gemini CLI may bypass the proxy entirely. Use Vertex AI authentication mode to ensure traffic flows through LiteLLM.

Benefits:

• Unified interface for 100+ LLM providers
• Built-in caching and cost tracking
• Team visibility and governance
• OpenAI-compatible API surface

Source: [Using Gemini CLI Through LiteLLM Proxy]((dev.to/redacted)

Other Compatible Gateways

• Portkey AI Gateway: Drop-in proxy with analytics and rate limiting
• Apigee AI Gateway: Google's API management for AI/ML governance
• Custom Proxies: Any proxy supporting GOOGLE_GEMINI_BASE_URL environment variable

Configuration Pattern

# Standard pattern for gateway integration
export GOOGLE_GEMINI_BASE_URL="(yourgateway.com/redacted)"
export GEMINI_API_KEY="gateway-auth-token"

# Gateway handles:
# - Routing to actual Gemini API
# - Authentication to Google
# - Rate limiting, logging, caching

---

4. Direct Google Gemini Endpoint Connection

Gemini-CLI connects to Google's Gemini API through two main pathways:

AI Studio API (Direct)

• Endpoint: `(generativelanguage.googleapis.com/redacted)
• Authentication: API key in x-goog-api-key header or ?key= query parameter
• Models: gemini-2.5-flash, gemini-2.5-pro, gemini-3-pro (preview)
• Rate limits: 60 req/min, 1,000 req/day (free tier)

Vertex AI API (Enterprise)

• Endpoint: https://{location}-aiplatform.googleapis.com/v1/projects/{project}/locations/{location}/publishers/google/models/{model}:generateContent
• Authentication: OAuth 2.0 tokens via Authorization: Bearer header
• Models: All Gemini models + enterprise features
• Features: Provisioned throughput, custom SLAs, VPC-SC support

Custom Endpoint Support (Feature Request)

There's an open feature request (#16504) to support custom API endpoints via:

export GOOGLE_GEMINI_BASE_URL="(customproxy.com/redacted)"
export GEMINI_API_KEY="custom-key"
````

**Status**: Currently only works for some ACP mode operations. Full support for custom base URLs is being developed.

**Source**: [GitHub Issue #16504](https://github.com/google-gemini/gemini-cli/issues/16504)

---

## 5. Agentic Architecture & ReAct Loop

### Core Architecture

Gemini-CLI is built as an **agentic system** using the **ReAct (Reason and Act) pattern**:

````
User Prompt → Intent Analysis → Tool Selection → Action Execution → Result Observation → Reasoning → Next Action

This iterative loop allows the agent to:

1. Reason about what needs to be done
2. Act by selecting and executing appropriate tools
3. Observe the results
4. Adapt its strategy based on outcomes

Built-in Tools

• File System: Read, write, edit, search files
• Shell Commands: Execute terminal commands with approval
• Web Fetch: Retrieve content from URLs
• Web Search: Google Search grounding for real-time information
• Git Operations: Clone, commit, branch, merge
• Code Execution: Run code in sandboxed environments

Extensibility via MCP (Model Context Protocol)

Gemini-CLI's true power comes from MCP integration, which allows adding custom tools:

// ~/.gemini/settings.json
{
  "model": "gemini-2.5-pro",
  "mcp_servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "`@modelcontextprotocol/server-github`"]
    },
    "custom-tool": {
      "command": "python",
      "args": ["my_mcp_server.py"],
      "env": {
        "API_KEY": "${YOUR_API_KEY}"
      }
    }
  }
}
````

### MCP Features
- **Standard Protocol**: JSON-RPC based, language-agnostic
- **Transport Options**: 
  - STDIO (standard in/out) for local processes
  - HTTP for remote services
- **Tool Discovery**: Automatic detection of available tools via `/mcp` command
- **Rich Content**: Return text, images, audio, binary data from tools

### MCP Server Ecosystem
- **FastMCP**: Python library for building MCP servers (`pip install fastmcp`)
- **Go SDK**: Official Go implementation
- **JavaScript SDK**: `@modelcontextprotocol/sdk`
- **Existing Servers**: GitHub, Firebase, Google Workspace, databases, custom APIs

### Multi-Agent Architecture (Roadmap)
There's a community proposal (#7637) for multi-agent orchestration:
- **Coordinator Agent**: Routes tasks to specialized agents
- **Specialized Agents**: React/Frontend, Node.js/Backend, DevOps, Testing
- **Event System**: Agent-to-agent communication
- **Agent Marketplace**: Discovery and installation of third-party agents

**Current Status**: Single-agent ReAct loop. Multi-agent is community-requested enhancement.

**Sources**: 
- [Multi-Agent Architecture Proposal](https://github.com/google-gemini/gemini-cli/discussions/7637)
- [InfoQ: Agentic Terminal CLI Agents]((www.infoq.com/redacted)
- [MCP Server Documentation]((geminicli.com/redacted)

---

## 6. Integration Recommendations for AW

Based on this research, here's how to integrate Gemini-CLI as an agentic engine in AW:

### Architecture Pattern
````
AW Workflow → LLM Gateway (Kong/LiteLLM) → Gemini CLI (Headless) → Gemini API
                     ↓                            ↓
            Observability/Control          MCP Tools/Extensions

Recommended Setup

1. Authentication: Use Vertex AI with ADC for production

   export GOOGLE_GENAI_USE_VERTEXAI=true
   export GOOGLE_CLOUD_PROJECT="aw-project-id"
   export GOOGLE_APPLICATION_CREDENTIALS="/secrets/service-account.json"

2. Gateway Integration: Route through Kong or LiteLLM

   export GOOGLE_GEMINI_BASE_URL="(awaigateway.com/redacted)
   export GEMINI_API_KEY="${GATEWAY_AUTH_TOKEN}"

3. Headless Execution: Use JSON output for parsing

   gemini -p "Your task" --output-format json --yolo > result.json

4. MCP Tools: Extend with AW-specific capabilities

   {
     "mcp_servers": {
       "aw-github": {
         "command": "npx",
         "args": ["`@modelcontextprotocol/server-github`"]
       },
       "aw-custom": {
         "command": "python",
         "args": ["/aw/agents/mcp_server.py"]
       }
     }
   }

Benefits for AW

• Observability: Gateway provides request logging, cost tracking
• Control: Rate limiting, content filtering, approval workflows
• Flexibility: Swap models without code changes
• Extensibility: Add custom tools via MCP
• Security: Centralized credential management

Considerations

• Initialization Time: 30-60s startup (can be optimized with persistent agent)
• Context Limits: 1M tokens (Gemini 2.5 Pro) - massive but not unlimited
• API Costs: Pay-per-token on Vertex AI, free tier on AI Studio (with limits)
• Gateway Overhead: Adds latency (~50-200ms) but provides critical governance

Key Sources

• [Gemini CLI Official Documentation]((googlegemini.github.io/redacted)
• Gemini CLI GitHub Repository
• [Kong AI Gateway Gemini Integration]((developer.konghq.com/redacted)
• [LiteLLM Gateway Documentation]((docs.litellm.ai/redacted)
• [MCP Protocol Documentation]((geminicli.com/redacted)
• [InfoQ: Agentic Terminal Lifecycle]((www.infoq.com/redacted)

Suggested Next Steps

1. Proof of Concept: Set up Gemini CLI in headless mode with Vertex AI authentication
2. Gateway Integration: Configure Kong AI Gateway or LiteLLM Proxy for traffic routing
3. Custom MCP Server: Build AW-specific tools using FastMCP or JavaScript SDK
4. Observability: Implement logging and cost tracking at the gateway level
5. Testing: Run automated tests in CI/CD pipeline using headless mode

---

Research completed: 2026-02-14 | Tools used: Tavily Search, GitHub, Microsoft Docs, arXiv

AI generated by Scout

[pelikhan]

We are doing cleanup to prepare for more engines.

[pelikhan]

Use port 10003 for Gemini.
Add a smoke-gemini agentic workflow.

[pelikhan]

Use subagent https://github.com/github/gh-aw/blob/main/.github/agents/custom-engine-implementation.agent.md to implement t this .