██████╗ ██████╗ 
 ██╔════╝██╔════╝ 
 ██║     ██║      
 ██║     ██║      
 ╚██████╗╚██████╗ 
  ╚═════╝ ╚═════╝ 
     G E M I N I

Use Claude Code — powered by Google Gemini. Free.

Run Anthropic's Claude Code CLI against Google's Gemini API instead of Anthropic's paid backend. One-command install · Zero side-effects on Claude · Safe uninstall · Multi-session

Install · Update · Uninstall · Usage · Reset/Flush · Full Reference →

How It Works

Your Terminal
    │
    ▼
cc-gemini                  ← This tool
    │
    │  ┌─────────────────────────────────────────────┐
    ├──│  LiteLLM Proxy  (port 8100–8199)             │
    │  │  Translates Anthropic API ↔ Gemini API       │
    │  └─────────────────────────────────────────────┘
    │
    ▼
Claude Code  (official Anthropic CLI)
    │
    ▼
Google Gemini API  ← Free tier, no Anthropic billing

Claude Code believes it is talking to Anthropic. Every request is transparently routed to Google Gemini. You get the full Claude Code experience — slash commands, file context, agent mode — without any Anthropic subscription.

Zero side-effects on Claude Code

cc-gemini never permanently modifies your Claude Code installation or credentials:

• Before each session it takes a snapshot of ~/.claude.json.
• After the session ends (exit, Ctrl+C, or crash) it restores the original file exactly.
• On uninstall it restores the pre-install state from a backup taken during npm install.
• The reset command can repair ~/.claude.json if a hard crash left a stale proxy key.

Prerequisites

| Requirement | Where to get it | |-------------|-----------------| | Node.js 18+ | https://nodejs.org | | npm (comes with Node.js) | — | | Google Gemini API key (free) | https://aistudio.google.com/apikey |

Python 3 and LiteLLM are installed automatically.

Installation

npm — recommended (all platforms)

npm install -g claude-code-gemini

This single command:

1. Installs the cc-gemini CLI globally.
2. Detects your OS and installs LiteLLM (with 5 fallback strategies for restricted environments — Docker, WSL, Codespaces, Lightning AI, etc.).
3. Installs Claude Code (@anthropic-ai/claude-code) if not already present.
4. Takes a backup of your current ~/.claude.json so it can be fully restored on uninstall.

Your Gemini API key is prompted on first run (not during install).

Alternative — shell installers

If you prefer not to use npm, classic shell-based installers are included.

Linux / macOS / WSL

chmod +x install.sh && ./install.sh
source ~/.bashrc    # or: source ~/.zshrc

Windows — PowerShell

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
.\install.ps1
. $PROFILE

Windows — CMD

install.bat

Update

npm update (recommended)

npm update -g claude-code-gemini

Or install the latest version explicitly:

npm install -g claude-code-gemini@latest

After updating, run cc-gemini doctor to verify all components are healthy.

Update model mappings only

No reinstall needed — model mappings can be updated at any time:

# Update a single mapping
cc-gemini models set claude-opus-4-8 gemini/gemini-2.5-pro

# Reset all mappings to the latest bundled defaults
cc-gemini models reset

# Interactive picker
cc-gemini models add

Uninstall

Standard uninstall (recommended)

npm uninstall -g claude-code-gemini

The preuninstall hook runs automatically before npm removes the package:

1. Stops every running cc-gemini proxy.
2. Restores ~/.claude.json to its exact pre-install state (from the backup taken during npm install).
3. Cleans up port lock files in $TMPDIR/claude-gemini/.

Note: ~/.claude-gemini/ (your API key, logs, model map) is intentionally kept so you do not lose settings if you reinstall. Delete it manually if you want a truly clean slate.

Full purge (remove everything)

# Step 1: wipe config directory and Python venv
cc-gemini uninstall --purge

# Step 2: remove the CLI
npm uninstall -g claude-code-gemini

Or manually on Linux/macOS:

rm -rf ~/.claude-gemini ~/.claude-gemini-venv
npm uninstall -g claude-code-gemini

On Windows (PowerShell):

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude-gemini"
Remove-Item -Recurse -Force "$env:USERPROFILE\.claude-gemini-venv"
npm uninstall -g claude-code-gemini

Verify Claude Code is unaffected after removal

claude --version
claude

If ~/.claude.json was accidentally left with the proxy key (sk-gemini-proxy), run:

# Surgical repair — removes only the proxy key, touches nothing else
cc-gemini reset

Or manually delete the "primaryApiKey" line from ~/.claude.json.

Reset / Flush

The reset command is a safe recovery tool that returns everything to a clean state without uninstalling:

cc-gemini reset      # standard reset
cc-gemini flush      # alias — identical effect

What it does:

1. Stops all running proxy instances.
2. Cleans up stale port lock files.
3. Resets the model map to factory defaults.
4. Clears all proxy log files.
5. Repairs ~/.claude.json — removes the stale proxy key if a crash left it behind.

cc-gemini reset --hard    # also clears stored Gemini API key

--hard additionally removes the stored Gemini API key so you are prompted to enter it again on next run. Useful when rotating API keys or starting completely fresh.

Usage

Start Claude Code with Gemini

cc-gemini

On first run you are prompted for your Gemini API key. On subsequent runs:

  [..] Existing Gemini API key: AIzaSyB1...y4k
  Continue with this key? [Y/n]:

Press Enter to continue, or type n to enter a different key.

Pass arguments directly to Claude Code

cc-gemini -- --no-auto-update
cc-gemini -- --model claude-opus-4-8
cc-gemini -- --dangerously-skip-permissions

Everything after -- is forwarded verbatim to claude.

Model Mapping

Claude Code uses Claude model names internally. cc-gemini maps those to real Gemini models via a YAML config file — editable at any time, no reinstall needed.

View mappings

cc-gemini models list

Update a mapping

cc-gemini models set claude-opus-4-8 gemini/gemini-2.5-pro

Add a mapping (interactive menu)

cc-gemini models add

Remove a mapping

cc-gemini models remove claude-haiku-4-5

Reset to defaults

cc-gemini models reset

Available Gemini models (May 2026)

| Model | Best For | |-------|----------| | gemini/gemini-3.5-flash | Coding & agentic tasks — recommended | | gemini/gemini-3.1-flash-lite | Fast, cheap, lightweight tasks | | gemini/gemini-3.1-pro-preview | Advanced reasoning (opus tier) | | gemini/gemini-2.5-pro | Most powerful, complex tasks | | gemini/gemini-2.5-flash | Price-performance balance | | gemini/gemini-2.5-flash-lite | Ultra-budget, 2.5 family |

Default tier mapping:

| Claude tier | Example model | Maps to | |---|---|---| | LITE (haiku) | claude-haiku-4-5 | gemini/gemini-3.1-flash-lite | | STANDARD (sonnet) | claude-sonnet-4-6 | gemini/gemini-3.5-flash | | PLUS (opus) | claude-opus-4-8 | gemini/gemini-3.1-pro-preview |

Parallel Sessions

Open multiple terminals and run cc-gemini in each — ports are managed automatically:

Terminal 1:  cc-gemini  →  proxy on port 8100
Terminal 2:  cc-gemini  →  proxy on port 8101
Terminal 3:  cc-gemini  →  proxy on port 8102

Check running instances:

cc-gemini status

Stop all instances:

cc-gemini stop

Stop a specific instance:

cc-gemini stop 8101

Command Reference

| Command | Description | |---------|-------------| | cc-gemini | Start Claude with Gemini proxy | | cc-gemini -- [args] | Pass flags/args to claude | | cc-gemini setup | Install & configure everything | | cc-gemini models list | Show model mappings | | cc-gemini models set <c> <g> | Update a mapping | | cc-gemini models add | Add a new mapping (interactive) | | cc-gemini models remove <c> | Remove a mapping | | cc-gemini models edit | Open mapping in $EDITOR | | cc-gemini models reset | Restore factory model defaults | | cc-gemini status | Show running proxy instances | | cc-gemini stop [port] | Stop one or all instances | | cc-gemini update-key | Change stored Gemini API key | | cc-gemini reset | Stop proxies, reset map, repair config | | cc-gemini reset --hard | Reset + clear stored API key | | cc-gemini flush | Alias for reset | | cc-gemini uninstall | Pre-removal cleanup + instructions | | cc-gemini uninstall --purge | Also removes config dir & Python venv | | cc-gemini doctor | Health-check all dependencies | | cc-gemini docs | Show full command reference | | cc-gemini version | Show version number | | cc-gemini help | Show help |

📖 Full Command Reference with examples →

Config & Files

~/.claude-gemini/                           (Linux/macOS)
%USERPROFILE%\.claude-gemini\               (Windows)
├── credentials                     ← Gemini API key  (mode 600)
├── model-mapping.yaml              ← Model mappings  (edit freely)
├── claude.json.pre-install-backup  ← Backup of ~/.claude.json
│                                      restored automatically on uninstall
└── logs/
    ├── proxy-8100.log              ← Per-session proxy logs
    └── ...

~/.claude-gemini-venv/              ← Python venv with LiteLLM

~/.claude.json is never permanently changed by cc-gemini. Any modification made during a session is automatically reversed when the session ends.

Troubleshooting

cc-gemini: command not found → Reload shell: source ~/.bashrc / source ~/.zshrc or open a new terminal.

Proxy fails to start / API errors → Check log: tail -20 ~/.claude-gemini/logs/proxy-8100.log → Verify key: cc-gemini update-key → Health check: cc-gemini doctor

Model deprecated / unknown model error → cc-gemini models set claude-opus-4-8 gemini/gemini-2.5-pro

"No free ports" error → cc-gemini stop then try again.

~/.claude.json left with sk-gemini-proxy key after a crash → cc-gemini reset — removes the stale key without touching anything else.

PowerShell: "execution of scripts is disabled"

Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

LiteLLM missing after OS upgrade / Python reinstall → cc-gemini setup — re-installs LiteLLM using the best available strategy.

Requirements

| Dependency | Version | Auto-installed | |------------|---------|----------------| | Node.js | 18+ | No — install from nodejs.org | | npm | any | With Node.js | | Python | 3.8+ | Checked at setup | | LiteLLM | latest | Yes (5 fallback strategies) | | Claude Code | latest | Yes |

Publishing to npm

# 1. Log in (one-time)
npm login

# 2. Bump version
npm version patch    # 1.0.0 → 1.0.1
# or
npm version minor    # 1.0.0 → 1.1.0

# 3. Publish
npm publish

# 4. Verify
npm info claude-code-gemini version

Only the contents of bin/, lib/, config/, scripts/, README.md, COMMANDS.md, and LICENSE are published (enforced by the files field in package.json).

License

MIT — see LICENSE for full text.

Author

Made by darkness0308. Issues and pull requests welcome at github.com/darkness0308/claude-code-gemini.