Skip to main content

Extension: Free Claude Code Setup with Google Gemini

This lesson provides a free alternative to use Claude Code using Google's free Gemini API as the backend. You'll learn the same Claude Code CLI interface and features covered in Lesson 2.

All features work identically: Subagents, skills, MCP servers, hooks, and all other capabilities covered in Lessons 3-9 function the same way with this free setup. The only difference is the backend AI model (Gemini instead of Claude) and the setup process (router configuration instead of direct authentication).

Reality Check: It's Just Copy-Paste​

Setup Complexity: Copy 3 text blocks, type 3 commands. That's it.

What you need:

  • Node.js 18+ (nodejs.org)
  • Free Google Account
  • 5 minutes

Verify Node.js (if unsure):

node --version  # Should show v18.x.x or higher

If missing, install from nodejs.org

Step 1: Get Your Free Google API Key​

  1. Go to: Google AI Studio
  2. Click "Get API Key"
  3. Sign in with Google
  4. Click "Create API Key"
  5. Copy the key (looks like: AIzaSyAaBbCcDd...)

Step 2: Copy-Paste Setup​

Just copy commands from this block and paste into terminal:

# Install tools
npm install -g @anthropic-ai/claude-code @musistudio/claude-code-router

# Create config directories
mkdir -p ~/.claude-code-router ~/.claude

# Create router config
# Create new config with native Gemini endpoint
cat > ~/.claude-code-router/config.json << 'EOF'
{
  "LOG": true,
  "LOG_LEVEL": "info",
  "HOST": "127.0.0.1",
  "PORT": 3456,
  "API_TIMEOUT_MS": 600000,
  "Providers": [
    {
      "name": "gemini",
      "api_base_url": "https://generativelanguage.googleapis.com/v1beta/models/",
      "api_key": "$GOOGLE_API_KEY",
      "models": [
        "gemini-2.5-flash",
        "gemini-2.0-flash"
      ],
      "transformer": {
        "use": ["gemini"]
      }
    }
  ],
  "Router": {
    "default": "gemini,gemini-2.5-flash",
    "background": "gemini,gemini-2.5-flash",
    "think": "gemini,gemini-2.5-flash",
    "longContext": "gemini,gemini-2.5-flash",
    "longContextThreshold": 60000
  }
}
EOF

# Verify file was created
cat ~/.claude-code-router/config.json

# Set your API key (REPLACE "YOUR_KEY_HERE" with actual key!)
echo 'export GOOGLE_API_KEY="YOUR_KEY_HERE"' >> ~/.zshrc
source ~/.zshrc

Windows users: Replace last 2 lines with:

# Windows PowerShell (Run as Administrator)
[System.Environment]::SetEnvironmentVariable('GOOGLE_API_KEY', 'YOUR_KEY_HERE', 'User')

# Then CLOSE and REOPEN PowerShell completely
# Verify it worked:
echo $env:GOOGLE_API_KEY

Bash users (older macOS/Linux):

# Check your shell first:
echo $SHELL

# If shows /bin/zsh → use ~/.zshrc (already done above)
# If shows /bin/bash → Change last 2 lines to:
echo 'export GOOGLE_API_KEY="YOUR_KEY_HERE"' >> ~/.bashrc
source ~/.bashrc

✅ Verify Setup Worked​

After pasting setup commands, verify immediately:

claude --version     # Should show: Claude Code v2.x.x
ccr --version        # Should show version number
echo $GOOGLE_API_KEY # Should show your key (not empty!)

# If any fail, see Troubleshooting section

✅ Done! That's the entire setup.

Step 3: Daily Workflow​

Every time you want to code:

# Terminal 1 - Start router FIRST
ccr start
# Wait for: ✅ Service started successfully

# Terminal 2 - THEN use Claude (after router is ready)
cd ~/your-project
eval "$(ccr activate)"
claude

That's it. One command in Terminal 1, three lines in Terminal 2. Just copy-paste!

Verification​

Start a Claude session:

claude

Say hi:

hi

Expected: Claude responds with a greeting confirming it's working! ✅ Success!

That's it. If Claude responds, your free setup is working perfectly.

Troubleshooting (Only 3 Things Go Wrong)​

Problem 1: "npm: command not found"

→ Install Node.js from https://nodejs.org/

Problem 2: "Connection refused"

→ Type `ccr start` in Terminal 1
→ Wait for: ✅ Service started successfully

Problem 3: "429 Too Many Requests"

→ You've hit your daily limit (1,500 requests)
→ Wait until midnight Pacific Time, or create new Google account
→ Check usage: https://aistudio.google.com/

That's it. Proceed to Lesson 3 to learn persistent project context.