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

Real-Time Quota Display

CCS displays real-time quota information for Gemini accounts via Dashboard and CLI.

Dashboard Display

Location: Dashboard → OAuth Providers → Gemini Displays:

Requests per minute (RPM) usage
Tokens per minute (TPM) usage
Requests per day (RPD) usage
Limit reset times

Backend Caching:

Quota data cached for 2 minutes to reduce API load
Automatic re-authentication if token expired
Dashboard shows cached timestamp

CLI Quota Check

# View quota for all Gemini accounts
ccs cliproxy quota --provider gemini

# Output:
# Gemini Quota (as of 2026-02-04 18:00:00):
#   john@gmail.com:
#     RPM: 45/60 requests (resets in 30s)
#     TPM: 28000/32000 tokens (resets in 30s)
#     RPD: 890/1500 requests (resets in 6h)

Features:

Displays all authenticated Gemini accounts
Shows cached timestamp (2-minute cache)
Proactive token refresh (5 minutes before expiry)

Quota Response Caching: CCS caches quota responses to prevent excessive API calls:

Cache Duration	Applies To
2 minutes	Quota data (usage counts, reset times)
Token refresh	Proactive (5min before expiry, matches CLIProxyAPI)

Cache Location: In-memory (not persisted to disk)

Tool Name Sanitization

Gemini enforces a 64-character limit on tool names. CCS automatically handles this via ToolSanitizationProxy.

The Problem

Claude MCP tools can have names exceeding 64 characters:

mcp__filesystem__read_multiple_files  # 37 chars - OK
mcp__sequential-thinking__recordThoughtSequence  # 50 chars - OK
mcp__very-long-server-name__someVeryLongToolNameHere  # 70+ chars - FAILS

Gemini API Error: “Invalid tool name: must be 64 characters or fewer”

How CCS Fixes It

ToolSanitizationProxy intercepts requests and:

Detects tool names exceeding 64 characters
Creates short hashes using <prefix>_<6-char-md5> format (e.g., mcp__long-server__toolName → mcp___a1b2c3)
Maintains bidirectional mapping
Restores original names in responses

Architecture

Claude CLI → ToolSanitizationProxy → CLIProxy → Gemini API
             ↓ Sanitize request      ↓ Forward    ↓ Process
             ↑ Restore response      ↑ Return     ↑ Respond

Proxy Lifecycle:

Spawned automatically when using Gemini provider
Runs on random port (127.0.0.1)
Shuts down with Claude session

Sanitization Process

Request Flow:

// Original (Claude CLI sends)
{
  "tools": [
    { "name": "mcp__very-long-server__someVeryLongToolNameThatExceeds64Chars" }
  ]
}

// Sanitized (Proxy → Gemini)
{
  "tools": [
    { "name": "mcp___a1b2c3" }
  ]
}

Response Flow:

// Gemini response
{
  "content": [
    { "type": "tool_use", "name": "mcp___a1b2c3" }
  ]
}

// Restored (Proxy → Claude CLI)
{
  "content": [
    { "type": "tool_use", "name": "mcp__very-long-server__someVeryLongToolNameThatExceeds64Chars" }
  ]
}

Debug Mode

Enable verbose logging to see sanitization activity:

export CCS_DEBUG=1
ccs gemini "use long tool names"

# Logs appear in: ~/.ccs/logs/tool-sanitization-proxy.log
# Console output (if CCS_DEBUG=1):
# [i] ToolSanitizationProxy started on port 54321
# [!] Sanitized 2 tool names (64-char limit)
# [i] Restored 1 tool name in response

Log Location: ~/.ccs/logs/tool-sanitization-proxy.log

When Sanitization Happens

Automatically enabled for:

All CLIProxy providers (gemini, codex, antigravity)
Any provider configured via config.cliproxy

Why all providers?

ToolSanitizationProxy runs for all CLIProxy-based providers to ensure compatibility across different model APIs

Configuration

Sanitization is automatic and requires no configuration. To disable warnings:

# config.yaml (not yet implemented - always warns)
cliproxy:
  tool_sanitization:
    warn_on_sanitize: false

Performance Impact

Minimal overhead:

Hash generation: under 1ms per tool
Request/response transformation: under 5ms
In-memory mapping (no disk I/O)

Timeout: 120 seconds (configurable via timeoutMs)

{
  "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 - Recommended (latest model, paid account required)
# 2. Gemini 2.5 Pro - Free tier (works with free Google account)
# Select model [1-2]: 1

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

Available Models

Model ID	Name	Tier	Notes
`gemini-3-pro-preview`	Gemini 3 Pro	Pro	Latest model, requires paid Google account
`gemini-2.5-pro`	Gemini 2.5 Pro	Free	Stable, works with free Google account

Gemini 3 Pro requires 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

​Quick Start

​Authentication

​Initial Setup

​OAuth Flow Specifics

​Headless Authentication

​Multi-Account Support

​Real-Time Quota Display

​Dashboard Display

​CLI Quota Check

​Tool Name Sanitization

​The Problem

​How CCS Fixes It

​Architecture

​Sanitization Process

​Debug Mode

​When Sanitization Happens

​Configuration

​Performance Impact

​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

Real-Time Quota Display

Dashboard Display

CLI Quota Check

Tool Name Sanitization

The Problem

How CCS Fixes It

Architecture

Sanitization Process

Debug Mode

When Sanitization Happens

Configuration

Performance Impact

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