Two terminal-native AI coding agents from two of the three leading AI labs. Both understand your codebase, both can run commands on your behalf, both are open source. The differences run deeper than the surface: Google's free tier and Search grounding are real differentiators, while Claude Code's 1M-token context and hooks system serve different workflows.
This comparison focuses on the technical and practical differences that affect real engineering work — not feature checklists.
| Factor | Claude Code | Gemini CLI |
|---|---|---|
| Underlying model | Claude Sonnet 4.6 / Opus 4.6 | Gemini 2.5 Pro |
| Context window | Up to 1M tokens | Up to 1M tokens |
| Install | npm install -g @anthropic-ai/claude-code | npm install -g @google/gemini-cli |
| License | Proprietary | Apache-2.0 (open source) |
| GitHub stars | Proprietary — no repo | 103k+ |
| Project config file | CLAUDE.md | GEMINI.md |
| Free tier | No — token-billed | Yes — 60 req/min, 1,000 req/day |
| MCP support | Yes (deep integration) | Yes |
| Google Search grounding | No | Yes — built-in |
| Hooks / lifecycle scripts | Yes (first-class) | No equivalent |
Both install via npm and work immediately from the terminal:
# Claude Code
npm install -g @anthropic-ai/claude-code
# Gemini CLI
npm install -g @google/gemini-cliClaude Code requires an Anthropic API key — every session is token-billed from the start. Gemini CLI can authenticate with a Google account and operate within the free tier: 60 requests per minute and 1,000 requests per day at no cost. This free path uses Gemini 2.5 Pro, Google's current frontier model — not a degraded free-tier model.
The free tier changes the entry calculus significantly. For a developer evaluating AI coding tools, Gemini CLI requires no financial commitment to start. Claude Code requires an API key and the willingness to accumulate token charges from session one.
Both tools run 1M-token context windows, which puts them in the same tier for large-codebase work. You can load entire repos, extensive documentation, and long conversation histories without hitting truncation.
Claude Code uses the Claude family — Sonnet 4.6 by default, Opus 4.6 for deep architectural work, Haiku 4.5 for fast cheap tasks. You switch with /model mid-session.
Gemini CLI uses Gemini 2.5 Pro. Google's model has notable strengths in multimodal tasks and tasks requiring live web knowledge — particularly when paired with the built-in Search grounding (more on that below). For pure code generation quality on complex multi-file changes, Claude's reasoning tends to produce more coherent output, but the gap is narrowing.
The 1M-token parity is meaningful: neither tool forces you to chunk or summarize a large codebase. Both can hold an entire repo in active context.
Both tools read a project config file you commit to the repo:
CLAUDE.md — loaded at every session start. Documents your stack, conventions, test commands, architectural decisions, and things to avoid. Supports nested files in subdirectories for per-package overrides. See the CLAUDE.md guide for a complete treatment.GEMINI.md — same concept and same placement. Documents project context, conventions, and workspace structure for Gemini to read at startup. The format and purpose are identical; the syntax is free-form markdown in both cases.In practice, CLAUDE.md has more documented patterns and community examples, since Claude Code has been shipping longer. GEMINI.md is functionally equivalent but has a smaller body of community lore to draw from. Both are plain markdown — pick whatever format communicates your project's constraints most clearly.
Gemini CLI ships with four named approval modes:
Plan Mode is Gemini CLI's strongest differentiator in this area. Before touching any file or running any command, it produces a structured breakdown of what it intends to do and why. You review the plan, approve it, and it executes without further interruption. This is useful for large refactors or multi-step tasks where you want to verify the approach before committing to execution — without having to approve each individual step.
Claude Code has a comparable plan mode, auto mode, and per-tool permission configuration. It also has a hooks system for programmatic lifecycle interception that Gemini CLI doesn't match — you can write scripts that block specific commands, audit file writes, or trigger downstream automation at any tool-call event.
Gemini CLI has native Google Search grounding built in. When Gemini determines that a query would benefit from current web information — a recent library release, a bug report, an API change — it can run a live Google Search and incorporate the results into its response, without you having to ask.
This is a material difference for tasks that touch moving targets: checking the current API for a library that updates frequently, verifying whether a CVE has been patched, understanding recent framework changes that postdate the model's training cutoff.
Claude Code doesn't have built-in web search. You can add a search MCP server (Brave Search, Tavily, etc.) via MCP configuration, but it's not native and requires separate setup. For developers working in fast-moving ecosystems where documentation gets stale quickly, Gemini's built-in search is a genuine productivity gain.
Gemini CLI is Apache-2.0 licensed with over 103,000 GitHub stars. You can read the full source, fork it, audit every code path, and submit changes back. This matters for enterprise environments where security teams require source auditability before approving AI tooling.
Claude Code is proprietary — Anthropic doesn't publish the source. For teams where open source is a hard procurement requirement, Gemini CLI clears the gate and Claude Code doesn't.
The open source status also means Gemini CLI can be self-hosted, customized, or integrated into internal tooling in ways that a proprietary binary can't match.
Claude Code has a first-class hooks system: shell scripts that execute at lifecycle events — before/after any tool call, on session start, on session stop. You can block dangerous commands (intercept rm -rf before execution), log all file writes to an audit trail, trigger notifications when long tasks complete, or run tests automatically after every edit. See the hooks guide for working examples.
Gemini CLI doesn't have an equivalent lifecycle interception system. You get the four approval modes for controlling execution flow, but not the programmatic hooks that let you enforce custom guardrails at the per-tool level. For teams that need compliance-auditable logs of every file write, or want to auto-enforce code style after every edit, Claude Code has a structural advantage here.
Both tools support Model Context Protocol for wiring in external tools and data sources. Claude Code's MCP integration is more mature — it was among the first tools to ship MCP support and the ecosystem of available servers is broader. See the Claude Code MCP guide for setup and commonly useful servers.
Gemini CLI also supports MCP servers and can itself expose tools via MCP, enabling it to act as a context provider for other MCP-compatible agents. For teams building multi-agent pipelines, both tools are viable MCP participants; Claude Code has more established patterns for wiring complex server configurations.
Gemini CLI includes a policy engine with five priority tiers that governs what the agent is permitted to do — from highest trust (system-level policies) down to the lowest (default safe behavior). This tiered policy system lets organizations deploy Gemini CLI with enforced behavioral boundaries separate from the approval mode — useful in enterprise environments where different teams or contexts need different permission levels without relying on per-session configuration.
Claude Code's equivalent is the per-tool permission configuration in settings.json, combined with hooks for more complex enforcement patterns. The policy system in Gemini CLI is more formally structured out of the box; Claude Code's approach is more flexible but requires more configuration to achieve equivalent enforcement.
| Path | Claude Code | Gemini CLI |
|---|---|---|
| Free tier | None — token-billed from first call | 60 req/min · 1,000 req/day with Google account |
| Entry point | Anthropic API key | Google account (free) or API key |
| Light dev (1 hr/day) | $30–80/mo (Sonnet) | Often within free tier |
| Moderate dev (2–3 hr/day) | $80–200/mo (Sonnet) | API key needed; competitive with Claude |
| Heavy use (4+ hr/day) | $150–400/mo (Sonnet/Opus mix) | Comparable at paid tier |
| Cost visibility | /cost command shows real-time spend | Google AI Studio dashboard |
The free tier is Gemini CLI's clearest pricing advantage. Developers who stay within 1,000 daily requests pay nothing. In practice, light-to-moderate coding sessions often fit within this limit — a few hours of focused work with short context windows can stay under 1,000 API calls.
At the paid tier, pricing is more competitive and depends on your specific usage patterns. Heavy agentic sessions with many tool calls and large context windows will cost meaningfully on either platform. Claude Code's /cost command gives real-time spend visibility that Gemini CLI doesn't match natively.
/cost command is essential for budget-conscious teamsThe free tier changes who can evaluate Gemini CLI. Claude Code requires financial commitment from session one; Gemini CLI doesn't. For individuals or small teams doing a serious evaluation, that's a meaningful practical difference — not just a pricing footnote.
Neither tool has built-in cross-session memory. Start a new Claude Code session and it doesn't remember yesterday's architectural decisions — CLAUDE.md gives you project context but not conversation history. Start a new Gemini CLI session and GEMINI.md does the same.
For most tasks this doesn't matter. For long-running projects where you want the agent to remember what approaches were tried, what was decided and why, and how the architecture evolved over weeks — neither tool solves this out of the box.
Beyond Your Ability (BYA) gives Claude Code persistent memory across sessions — so it remembers your project decisions, what was tried and why it didn't work, and how your architecture evolved. No more re-explaining the same context every morning.
See how BYA works →