Skip to main content
Google Gemini is Cluely’s default AI provider, offering the latest AI technology with native vision capabilities and fastest response times.

​
Features

  • Latest AI Technology: Gemini 2.5 Flash with advanced reasoning
  • Native Vision: Direct image and screenshot analysis
  • Audio Processing: Built-in transcription and audio analysis
  • Fast Responses: Cloud-optimized for minimal latency
  • Automatic Fallback: Switch to backup API key on rate limits

​
Setup

1

Get API Key

Visit Google AI Studio and create a new API key.
You can create multiple API keys for fallback protection against rate limits.
2

Configure Environment

Add your API key(s) to the .env file in the project root:
GEMINI_API_KEY=your_primary_api_key_here
GEMINI_FALLBACK_API_KEY=your_backup_api_key_here
Keep your API keys secure. Never commit .env files to version control.
3

Verify Configuration

Start Cluely and check the console for:
[LLMHelper] Using Google Gemini

​
Configuration Options

​
Environment Variables

VariableRequiredDescriptionDefault
GEMINI_API_KEYYes*Primary API key-
GEMINI_FALLBACK_API_KEYNoBackup API key for rate limits-
*Required unless using Ollama, OpenRouter, or K2 Think V2

​
Default Model

Cluely uses models/gemini-2.5-flash by default for optimal balance of speed and quality. 
// Default configuration (source/electron/LLMHelper.ts:26)
private geminiModel: string = "models/gemini-2.5-flash"

​
Switching to Gemini at Runtime

// Switch from another provider to Gemini
await llmHelper.switchToGemini(apiKey, model)

// Or use default configuration
await llmHelper.switchToGemini()

​
Features in Detail

​
Automatic Fallback

When rate limits are hit, Cluely automatically switches to your fallback API key: 
// Automatic fallback logic (source/electron/LLMHelper.ts:139-145)
if (isRateLimitError && !this.usingFallbackKey && this.fallbackGeminiApiKey) {
  console.log(`[LLMHelper] Rate limit hit, switching to fallback API key...`);
  this.geminiApiKey = this.fallbackGeminiApiKey;
  this.model = new GoogleGenAI({ apiKey: this.fallbackGeminiApiKey });
  this.usingFallbackKey = true;
}
Set up a fallback key to avoid interruptions during high usage periods.

​
Error Handling

Cluely includes retry logic with exponential backoff for transient errors:
Automatically retries with fallback API key when available.Detected error patterns:
  • HTTP 429 status
  • “quota” in error message
  • “RATE_LIMIT” or “RESOURCE_EXHAUSTED” errors

​
Vision Capabilities

Gemini provides native image analysis for screenshots: 
// Image analysis example
const imageParts = await Promise.all(
  imagePaths.map(path => this.fileToGenerativePart(path))
)

const result = await this.generateContentWithRetry([
  { parts: [{ text: prompt }, ...imageParts] }
])
Supported Features:
  • Screenshot analysis for coding problems
  • Error message interpretation
  • Document and presentation parsing
  • Multi-image context understanding

​
Audio Processing

Gemini handles audio transcription and analysis: 
// Audio analysis example
const audioPart = {
  inlineData: {
    data: audioData.toString("base64"),
    mimeType: "audio/mp3"
  }
}
Supported Formats:
  • MP3 audio files
  • Base64-encoded audio streams

​
Best Practices

  • Use separate API keys for development and production
  • Set up fallback keys to handle rate limits
  • Monitor usage in Google AI Studio
  • Rotate keys periodically for security
  • Configure GEMINI_FALLBACK_API_KEY for automatic failover
  • Monitor console logs for rate limit warnings
  • Consider Ollama for high-volume local usage
Watch for these console messages:
# Success
[LLMHelper] Using Google Gemini

# Fallback activated
[LLMHelper] Rate limit hit, switching to fallback API key...

# Retry attempt
[LLMHelper] Model overloaded, retrying in 1000ms... (attempt 1/3)

​
Voice Features

Voice features always use Gemini, even when other providers are configured for text chat.
Cluely uses a dedicated Gemini client for voice operations: 
// Separate client for voice (source/electron/LLMHelper.ts:36)
private geminiVoiceClient: GoogleGenAI | null = null
This ensures reliable voice transcription and response generation regardless of your primary AI provider.

​
Troubleshooting

Error: Either provide Gemini API key, enable Ollama mode, enable K2 Think, or provide OpenRouter API keySolution:
  1. Verify .env file exists in project root
  2. Check GEMINI_API_KEY is set correctly
  3. Restart the application after updating .env
Error: 429 or RATE_LIMIT_EXCEEDEDSolution:
  1. Set up GEMINI_FALLBACK_API_KEY in .env
  2. Wait for quota to reset (usually within minutes)
  3. Consider upgrading to higher tier in Google AI Studio
Error: Voice or image analysis returns empty resultsSolution:
  1. Check API key has sufficient quota
  2. Verify image format is supported (PNG recommended)
  3. Ensure audio is in MP3 format
  4. Check console for detailed error messages

​
Next Steps

Ollama Setup

Configure local AI for privacy-first usage

OpenRouter Setup

Access multiple AI models through one API

Build docs developers (and LLMs) love

Get started for freeTalk to us