Switching from Claude Code to Gemini CLI: Free Alternative Migration Guide (2026)

Updated: June 2026 · How we test tools →

You're switching from Claude Code to Gemini CLI. The reason is probably simple: Claude Code costs $20/month, hits rate limits during intense sessions, and has no free tier. Gemini CLI is free — 1,000 requests per day with Gemini 2.5 Pro, no credit card, no subscription. Both are terminal-first CLI coding agents. The workflow is similar enough that migration takes under 15 minutes.

This guide walks you through the full switch.

What You're Gaining and Losing

You'll gain:

$0/month — Gemini CLI is completely free for up to 1,000 requests/day
No rate limits within the free tier (1,000 requests covers most developer days)
1M token context window — same as Claude Code's beta, standard in Gemini CLI
Built-in Google Search grounding — research current library APIs during implementation
Multimodal input — feed it screenshots, PDFs, diagrams directly in the terminal
Open-source (Apache 2.0) — auditable code
No account lock-in — just a Google account you likely already have

You'll lose:

Claude model quality — Gemini 2.5 Pro is strong but Claude Sonnet/Opus outperforms it on the hardest reasoning tasks
Claude Code's polished agent loop on very complex multi-step sessions
Local model support — Gemini CLI is Google-model-only, no Ollama

The honest trade-off: For routine coding tasks — implementing features, writing tests, refactoring bounded modules — the quality difference between Gemini 2.5 Pro and Claude Sonnet is small. For the hardest autonomous tasks requiring sustained reasoning, Claude has a meaningful edge. For most developer days, you won't notice a difference.

If you want the full comparison before deciding, see Claude Code vs Gemini CLI →. If cost was your driver, see Claude Code Too Expensive? →.

Step 1: Get Your Free Google AI Studio API Key

You need a Google AI Studio API key to use Gemini CLI. It takes about 2 minutes.

Go to aistudio.google.com
Sign in with any Google account
Click Get API key → Create API key
Copy the key (starts with AIza...)

Free tier details: Your key automatically gets the free tier — 1,000 requests/day with Gemini 2.5 Pro, 1M token context window. No credit card required. No expiry.

If you want more: Google AI Studio's paid tier via API billing starts at very low per-token rates. For most developers, the free 1,000 requests/day never needs supplementing.

Step 2: Install Gemini CLI

# Install globally via npm (requires Node.js 18+)
npm install -g @google/gemini-cli

# Verify installation
gemini --version

Check Node.js version:

node --version
# Should be v18 or higher

If you need to update Node.js:

# macOS with Homebrew
brew install node

# Or use nvm
nvm install 20
nvm use 20

Step 3: Authenticate with Your API Key

# Set your API key as an environment variable
export GEMINI_API_KEY=your-key-here

# Persist across sessions
echo 'export GEMINI_API_KEY=your-key-here' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

# Verify it works
gemini --version

Alternative: interactive login

gemini
# On first run, it prompts for authentication
# Choose "API Key" → paste your key

Step 4: Run Gemini CLI for the First Time

Navigate to one of your projects and start a session:

cd ~/projects/my-project
gemini

Gemini CLI opens an interactive session similar to Claude Code's terminal interface. You can:

Describe tasks in plain English and it executes them
Ask questions about your codebase
Request multi-file edits
Run commands and see output

Try a quick test:

> Summarise the structure of this project in 3 sentences.

If it responds with an accurate summary of your project, the setup is working correctly.

Step 5: Migrate Your CLAUDE.md Context

Claude Code reads CLAUDE.md automatically. Gemini CLI handles project context differently — you pass it at the start of a session or reference it inline.

Find your CLAUDE.md files

find ~/projects -name "CLAUDE.md" -type f

Pass CLAUDE.md context to Gemini CLI

Method 1 — At session start (recommended):

cd my-project
gemini

# First message in the session:
> Please read the project conventions in CLAUDE.md before we start: $(cat CLAUDE.md)

Method 2 — Reference the file directly:

> @CLAUDE.md
# Gemini CLI reads and loads the file contents

Method 3 — Use a GEMINI.md file: Create a GEMINI.md at your project root with the same content as your CLAUDE.md. While Gemini CLI doesn't auto-read it, naming it clearly helps you remember to load it:

cp CLAUDE.md GEMINI.md
# Edit GEMINI.md to remove Claude-specific instructions if any

Best practice for consistent sessions: Create a shell alias that opens Gemini CLI with your project context pre-loaded:

# Add to ~/.zshrc or ~/.bashrc
alias gdev='gemini --prompt "$(cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found")\n\nReady to help with this project. What would you like to work on?"'

Then just run gdev from any project directory.

Step 6: Learn the Gemini CLI Workflow

Gemini CLI's interaction model is similar to Claude Code but with some differences. Here's the mapping:

Claude Code	Gemini CLI
`claude "implement X"`	`gemini` → describe task in session
`/add file.py`	`> @file.py` to reference a file
`/clear` context	Start new session (exit and re-run `gemini`)
`git diff` review	Git auto-commits not default — use `git diff` manually
CLAUDE.md auto-loaded	Pass context manually at session start
Rate limit → pause	1,000 req/day free — rarely hit
MCP tool integrations	MCP supported — configure in settings

Key workflow difference — Git commits: Claude Code auto-commits changes by default. Gemini CLI does not auto-commit — changes are applied to files, but committing is your responsibility. This is actually more conservative. After a Gemini CLI session:

git diff                    # review what changed
git add -p                  # stage selectively
git commit -m "feat: ..."   # commit with your message

If you want Gemini CLI to handle commits:

> After making the changes, also create a git commit with an appropriate message.

Step 7: Use Gemini CLI's Unique Features

These features don't exist in Claude Code — they're reasons to use Gemini CLI rather than just tolerating it as a free substitute.

Built-in Google Search

Gemini CLI can search the web during an implementation session. This is particularly useful when working with libraries that change frequently:

> Implement a data upload handler for the Google Cloud Storage Node.js SDK.
  Check the current API if needed — the library may have changed recently.

Gemini CLI searches current documentation and implements against today's API, reducing hallucinated outdated method calls — a common pain point with any AI coding tool trained on older data.

Multimodal Input

Pass images, PDFs, or diagrams directly into the session:

# Feed a UI screenshot
> @screenshot.png
> Implement this UI component in React using Tailwind CSS.

# Feed a PDF specification
> @api-spec.pdf
> Implement the authentication flow described in Section 3 of this document.

# Feed an architecture diagram
> @system-diagram.png
> Create the service structure shown in this diagram.

Claude Code has some multimodal support but Gemini's is deeper — it's a core capability of Google's model stack.

1M Token Context — Standard, Not Beta

Claude Code's 1M token context is currently in beta and not available to all users. Gemini 2.5 Pro's 1M token context is available to all free users. For large codebases:

# Gemini CLI can load large codebases without context window issues
gemini

> Load all TypeScript files in the src/ directory and explain the overall architecture.

Step 8: Configure MCP Integrations

If you used MCP servers with Claude Code, Gemini CLI supports MCP too.

# Gemini CLI settings file location
~/.gemini/settings.json

# Example MCP configuration (same format as Claude Code)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

The Hybrid Approach: Gemini CLI + Claude Code

Many developers use both — this is the optimal cost strategy:

Gemini CLI for: Daily feature work, test writing, documentation, code review, routine refactors, any task where Gemini 2.5 Pro is adequate (which is most tasks).

Claude Code (or Aider + Claude API) for: The hardest tasks — very complex multi-file autonomous refactors, nuanced debugging requiring sustained reasoning, architectural decisions on large codebases.

With this setup, you might spend $0–5/month on Claude Code (or Aider BYOK) for hard tasks and $0 on Gemini CLI for everything else — compared to $20/month flat for Claude Code alone.

Cost Comparison

	Claude Code	Gemini CLI
Monthly cost	$20 (Pro) — $100–200 (Max)	$0 for 1,000 req/day
Free tier	None	✅ Always free
Annual cost	$240+	$0
Rate limits	Hit after 3–5h intensive use	1,000 req/day — rarely hit
Hard task supplement	Included	~$0–10/mo Aider + Claude API

See Claude Code Rate Limits → for the full rate limit context, and Free Claude Code Alternatives → for a comparison of all free options.

What to Expect in Your First Week

Day 1: Sessions feel familiar — both are terminal-first conversational agents. The main adjustment is manually loading CLAUDE.md context at session start. Create the gdev alias from Step 5 to automate this.

Day 2–3: You'll notice Gemini CLI's Google Search grounding when implementing against third-party APIs. It's one of the clearest practical advantages over Claude Code.

Day 4–5: Find a task that genuinely challenges Gemini CLI — something complex where you'd have previously relied on Claude Code's deeper reasoning. This reveals whether the free tier meets your actual needs.

Week 1 end: Evaluate your real usage. Most developers find that Gemini CLI handles 85–90% of their daily tasks without noticeable quality difference. The 10–15% where Claude's reasoning depth matters is where a targeted Claude API spend (via Aider) is worth it.

Quick Reference: Gemini CLI Cheat Sheet for Claude Code Switchers

SETUP (one time)
──────────────────────────────────────────────────
aistudio.google.com → Get API key → copy
npm install -g @google/gemini-cli
export GEMINI_API_KEY=your-key-here  (add to ~/.zshrc)

START A SESSION
──────────────────────────────────────────────────
gemini                              → start interactive session
gemini -p "one-off prompt here"     → non-interactive single prompt
gemini --model gemini-2.5-pro       → explicit model (default)

IN SESSION
──────────────────────────────────────────────────
@filename              → reference/load a file
@CLAUDE.md             → load project conventions
> implement X          → agentic task
> explain this code    → Q&A about codebase
exit                   → end session

GEMINI CLI UNIQUE FEATURES
──────────────────────────────────────────────────
Web search  → ask about current library APIs, Gemini searches live
@image.png  → feed a screenshot or diagram
@spec.pdf   → feed a PDF specification
1M context  → load large codebases freely (standard, not beta)

GIT (manual — Gemini CLI doesn't auto-commit)
──────────────────────────────────────────────────
git diff               → review what changed
git add -p             → stage selectively
git commit -m "..."    → commit yourself
OR ask Gemini: "commit these changes with an appropriate message"

FAQ

Is Gemini CLI really free? Yes. 1,000 requests per day with Gemini 2.5 Pro using a Google AI Studio API key — no credit card, no trial period, no expiry. The free tier doesn't degrade or change. For usage above 1,000 requests/day, Google AI Studio billing starts at low per-token rates.

Is Gemini CLI as good as Claude Code? For routine coding tasks — implementing features, writing tests, refactoring bounded modules — the quality difference is small. For the hardest multi-step autonomous reasoning tasks, Claude Code's models have a meaningful edge. See Claude Code vs Gemini CLI → for the detailed comparison.

Does Gemini CLI auto-commit to Git like Claude Code? No. Gemini CLI applies file changes but doesn't auto-commit. You review changes with git diff and commit yourself — or ask Gemini to commit for you at the end of a session.

Can I use Gemini CLI offline? No. Gemini CLI requires internet access to Google's API. For offline or air-gapped environments, Aider with Ollama is the right option.

What happens when I hit the 1,000 request/day limit? The API returns a rate limit error. Options: wait until the next day (limits reset at midnight UTC), switch to a paid Google AI Studio tier, or use a different tool for the rest of the day. In practice, 1,000 requests covers full-day development for most developers.

Can I use both Gemini CLI and Claude Code? Yes. This is the recommended hybrid strategy: Gemini CLI for daily work, Claude Code or Aider + Claude API for the hardest tasks. They don't conflict — both run in the terminal and operate on the same files.

Does Gemini CLI support MCP? Yes. The MCP configuration format is similar to Claude Code's. See Step 8 above for the configuration example.

Migration guides: Claude Code → Cursor → · Claude Code → Aider → · Claude Code → Cline → · Claude Code → Windsurf → · Explore CLI Agents → · Full Claude Code alternatives →