Gemini Provider

Access Google Gemini models via OAuth authentication with automatic token management and interactive model configuration.

Quick Start

# First run (browser opens for OAuth)
ccs gemini "explain this code"

# Select model interactively
ccs gemini --config

# Use specific account
ccs gemini --use work

Authentication

Initial Setup

First Run

Run ccs gemini "your prompt" - browser opens automatically

Google OAuth

Token Cached

OAuth token saved to ~/.ccs/cliproxy/auth/gemini-{email}.json

Auto Refresh

Token refreshes automatically 5 minutes before expiry

OAuth Flow Specifics

Authorization Code Flow:

Callback server spawns on provider-specific port
Browser opens for Google OAuth consent
Token received via HTTP callback
Auto-refresh prevents mid-request failures

Proactive Token Refresh:

Checks expiry_date before each execution
Refreshes 5 minutes before expiry (matches CLIProxyAPI)
Prevents UND_ERR_SOCKET errors during long sessions
Graceful re-auth prompt if refresh fails

Headless Authentication

For servers without browser access:

ccs gemini --headless

# Output:
# Open this URL on any device:
# https://accounts.google.com/o/oauth2/auth?...
#
# Waiting for authentication...

Complete OAuth on another device - CCS detects when token is cached.

Multi-Account Support

Manage multiple Google accounts seamlessly:

Add Account
List Accounts
Switch Account

# Add second account (preserves existing)
ccs gemini --auth --add

# Auto-nicknamed from email prefix
# john@gmail.com → "john"

ccs gemini --accounts

# Output:
# Available Gemini accounts:
# * john (john@gmail.com) - default
#   work (alice@company.com)

# Switch default account
ccs gemini --use work

# Rename account
ccs gemini --nickname personal

Account Registry: ~/.ccs/cliproxy/accounts.json

{
  "version": 1,
  "providers": {
    "gemini": {
      "default": "john@gmail.com",
      "accounts": {
        "john@gmail.com": {
          "email": "john@gmail.com",
          "nickname": "john",
          "tokenFile": "gemini-john@gmail.com.json",
          "createdAt": "2024-01-01T00:00:00Z",
          "lastUsedAt": "2024-01-05T12:00:00Z"
        }
      }
    }
  }
}

Model Configuration

Interactive Model Picker

Select Gemini model interactively with --config flag:

ccs gemini --config

# Interactive prompt:
# Available models for Gemini:
# 1. Gemini 3 Pro (High) - Recommended (fast, reliable)
# 2. Gemini 3 Pro (Preview) - Latest features (may be unstable)
# 3. Gemini 2.5 Pro - Free tier
# 4. Gemini 3 Flash - Fast responses
# Select model [1-4]: 1

First-Run Detection: If no model configured, prompts automatically before first execution.

Available Models

Model ID	Name	Tier	Notes
`gemini-3-pro-high`	Gemini 3 Pro (High)	Paid	Recommended, fast & reliable
`gemini-3-pro-preview`	Gemini 3 Pro (Preview)	Paid	Latest features, may be unstable
`gemini-2.5-pro`	Gemini 2.5 Pro	Free	Works with free Google account
`gemini-3-flash`	Gemini 3 Flash	Paid/Free	Fast responses, lower quality

Gemini 3 Pro models require a paid Google account. Use Gemini 2.5 Pro for free tier.

Model Settings Storage

Settings saved to ~/.ccs/gemini.settings.json:

{
  "model": "gemini-3-pro-high",
  "maxTokens": 8192
}

Priority: Custom settings → User overrides → Bundled defaults

Configuration

Config Keys

Configure via ~/.ccs/config.yaml:

# WebSearch integration
websearch:
  providers:
    gemini:
      model: "gemini-2.5-pro"      # Model for WebSearch hook
      timeout: 30000                # CLI timeout (ms)

# CLIProxy settings
cliproxy:
  auth:
    api_key: "ccs-internal-managed"
    management_secret: "ccs"        # Dashboard login password

Environment Variables

These are set automatically by CCS. Manual override rarely needed.

# Claude CLI injection (auto-managed)
ANTHROPIC_BASE_URL=http://127.0.0.1:8317/api/provider/gemini
ANTHROPIC_AUTH_TOKEN=ccs-internal-managed
ANTHROPIC_MODEL=gemini-3-pro-high
ANTHROPIC_DEFAULT_OPUS_MODEL=gemini-3-pro-high
ANTHROPIC_DEFAULT_SONNET_MODEL=gemini-3-flash
ANTHROPIC_DEFAULT_HAIKU_MODEL=gemini-3-flash
ANTHROPIC_MAX_TOKENS=8192

Commands Reference

Basic Usage

# Execute with default model
ccs gemini "your prompt"

# One-shot mode (exit after response)
ccs gemini "explain this function"

Authentication Commands

# Trigger OAuth (no session)
ccs gemini --auth

# Add new account (preserves existing)
ccs gemini --auth --add

# Logout (clear tokens)
ccs gemini --logout

# Headless mode (no browser)
ccs gemini --headless

Account Management

# List all accounts
ccs gemini --accounts

# Switch default account
ccs gemini --use work

# Rename current account
ccs gemini --nickname personal

Configuration

# Interactive model picker
ccs gemini --config

# Dashboard configuration
ccs config

Troubleshooting

Token Refresh Failures

Symptom: UND_ERR_SOCKET errors during execution Cause: Token expired mid-request Solution: Proactive refresh handles this automatically. If issue persists:

# Clear and re-authenticate
ccs gemini --logout
ccs gemini --auth

Model Not Working

Symptom: API errors, tool call failures Cause: Model incompatible with Claude Code Solution: Change model via --config:

ccs gemini --config
# Select "Gemini 3 Pro (High)" - most reliable

Gemini 3 Pro (Preview) has known issues with tool calls. Use “High” variant instead.

Multiple Accounts Confusion

Symptom: Wrong account being used Solution: Check default account:

# View all accounts (default marked with *)
ccs gemini --accounts

# Switch default
ccs gemini --use work

Browser Doesn’t Open

Symptom: OAuth flow stuck waiting for browser Solution: Use headless mode:

ccs gemini --headless
# Copy URL to browser manually

Storage Locations

Path	Description
`~/.ccs/cliproxy/auth/gemini-*.json`	OAuth tokens (one per account)
`~/.ccs/cliproxy/accounts.json`	Account registry, nicknames
`~/.ccs/gemini.settings.json`	Model selection, preferences
`~/.ccs/cliproxy/config.yaml`	CLIProxy configuration

Cost Information

Tier	Models	Cost
Free	Gemini 2.5 Pro, Gemini 3 Flash (limited)	$0
Paid	Gemini 3 Pro (High/Preview)	Google subscription required

Quota Management: Automatic rotation if rate limited (config: quota-exceeded.switch-project: true)

Advanced Features

Token Structure

OAuth token file format (gemini-{email}.json):

{
  "type": "gemini",
  "access_token": "ya29...",
  "refresh_token": "1//...",
  "email": "user@gmail.com",
  "expired": "2024-12-31T23:59:59Z",
  "expiry_date": 1735689599000
}

Proactive Refresh Logic

Before execution: Check expiry_date
If < 5 minutes until expiry: Trigger refresh
If refresh succeeds: Update token file
If refresh fails: Prompt re-auth
Execute Claude CLI with valid token

Why 5 minutes? Matches CLIProxyAPI behavior, prevents race conditions during long API calls.

Next Steps

Multi-Account Setup

Configure multiple Google accounts

Model Selection

Choose optimal Gemini model

Remote Proxy

Connect to external CLIProxy server

WebSearch Integration

Enable Gemini-powered web search

Getting Started

Providers

Features

Tutorials

Gemini Provider

Gemini Provider

Quick Start

Authentication

Initial Setup

OAuth Flow Specifics

Headless Authentication

Multi-Account Support

Model Configuration

Interactive Model Picker

Available Models

Model Settings Storage

Configuration

Config Keys

Environment Variables

Commands Reference

Basic Usage

Authentication Commands

Account Management

Configuration

Troubleshooting

Token Refresh Failures

Model Not Working

Multiple Accounts Confusion

Browser Doesn’t Open

Storage Locations

Cost Information

Advanced Features

Token Structure

Proactive Refresh Logic

Next Steps

Multi-Account Setup

Model Selection

Remote Proxy

WebSearch Integration

Getting Started

Providers

Features

Tutorials

​Gemini Provider

​Quick Start

​Authentication

​Initial Setup

​OAuth Flow Specifics

​Headless Authentication

​Multi-Account Support

​Model Configuration

​Interactive Model Picker

​Available Models

​Model Settings Storage

​Configuration

​Config Keys

​Environment Variables

​Commands Reference

​Basic Usage

​Authentication Commands

​Account Management

​Configuration

​Troubleshooting

​Token Refresh Failures

​Model Not Working

​Multiple Accounts Confusion

​Browser Doesn’t Open

​Storage Locations

​Cost Information

​Advanced Features

​Token Structure

​Proactive Refresh Logic

​Next Steps

Multi-Account Setup

Model Selection

Remote Proxy

WebSearch Integration

Gemini Provider

Quick Start

Authentication

Initial Setup

OAuth Flow Specifics

Headless Authentication

Multi-Account Support

Model Configuration

Interactive Model Picker

Available Models

Model Settings Storage

Configuration

Config Keys

Environment Variables

Commands Reference

Basic Usage

Authentication Commands

Account Management

Configuration

Troubleshooting

Token Refresh Failures

Model Not Working

Multiple Accounts Confusion

Browser Doesn’t Open

Storage Locations

Cost Information

Advanced Features

Token Structure

Proactive Refresh Logic

Next Steps