Google shipped Gemini CLI as an open-source terminal agent in mid-2025, and by 2026 it has settled into a clear niche: a free, locally-run coding agent that competes on context size rather than polish. You install it, point it at a repository, and it reads files, edits them, and runs commands through a reasoning loop without leaving your shell. We ran it against real projects — a mid-sized TypeScript app and a Python service with a sprawling test suite — to see where it earns a seat next to Claude Code and Aider, and where it still gets in your own way.
How Gemini CLI actually works
Gemini CLI is released under Apache 2.0, so the source is public and you can audit exactly what it sends and runs. You install it with npm install -g @google/gemini-cli (or run it once with npx), then authenticate. Signing in with a personal Google account unlocks the free tier; dropping in a Gemini API key or a Vertex AI project routes you to paid, higher-limit usage instead.
Under the hood it runs a ReAct-style loop: the model reasons about your request, calls a tool, reads the result, and repeats until the task is done or it asks you to confirm something. The built-in toolset is the part that makes it an agent rather than a chat box — it can read and write files, grep across the tree, run shell commands, and fetch web pages. Because it's a Google product, web search grounding is wired straight in, so it can pull current documentation mid-task instead of guessing from training data.
Two features matter more than the feature list suggests. First, a GEMINI.md file at your repo root acts as persistent project context — conventions, architecture notes, commands to never run — that gets loaded on every invocation, the same pattern as Claude Code's CLAUDE.md. Second, Gemini CLI speaks the Model Context Protocol (MCP), so you can attach external servers (a database, an issue tracker, your own internal tools) and the agent treats them as first-class capabilities.
Where it earns a place in your workflow
The headline advantage is context. Gemini 2.5 Pro carries a 1-million-token context window, and the CLI is built to exploit it. When you ask it to reason across a dozen interlinked files, it can hold far more of the codebase in working memory than agents capped at smaller windows. On the TypeScript app, it traced a bug from a React component through two utility modules and a config file in a single pass, without us manually feeding it each file — the kind of cross-file reasoning that smaller-context tools fumble.
The second advantage is price. The free tier, authenticated with a Google account, gives you a genuinely usable daily allowance — at launch it permitted dozens of requests per minute and up to roughly a thousand per day, though Google has adjusted these quotas over time, so check the current limits before you build a workflow around them. For solo developers and side projects, that's enough to lean on it daily without a bill.
Where does it sit against the alternatives? Claude Code is the more polished agent — its editing precision and multi-step task discipline are still ahead. Aider remains the lighter, more deterministic choice when you want tight git-diff control and pair-programming-style edits. Gemini CLI splits the difference: more autonomous than Aider, less consistent than Claude Code, and unbeatable on cost-per-token for large-context work.
Write a
GEMINI.mdbefore your first real session. List the commands the agent must never run (destructive migrations,git push --force), the test command, and your formatting rules. The agent's quality jumps noticeably when it stops guessing your conventions on every turn — this single file does more for output quality than any prompt tweak.
A practical note on the non-interactive mode: you can pipe a prompt in and get a single response out, which makes Gemini CLI scriptable. We used it to generate commit-message drafts and to summarize what a PR changed, both as one-line shell invocations. It's not a replacement for a CI agent, but it's a legitimate building block for automation.
Limits worth knowing before you commit
Editing precision is the recurring weak spot. On larger refactors, Gemini CLI occasionally produced edits that didn't apply cleanly, or rewrote more of a file than the task required. You'll want to review every diff rather than rubber-stamp it — which is good practice regardless, but with Claude Code we trusted the diffs more often.
It also loops. When a tool call fails — a shell command errors, a file path is wrong — the agent sometimes retries the same approach instead of stepping back. You'll see it burn a few turns before it adjusts, and on the free tier those wasted turns count against your quota. Keeping tasks scoped (one bug, one feature, one file group at a time) kept it on track far better than open-ended "fix everything" prompts.
Finally, model behavior varies by version. Google updates the underlying Gemini models on its own cadence, and a workflow that felt reliable one month can shift after a model update. Pin your expectations to behavior you verify, not to a benchmark you read.
Gemini CLI can run shell commands, and the free-tier autonomy makes it tempting to let it work unattended. Don't run it with broad permissions inside a repo that has production credentials, uncommitted work you can't lose, or destructive scripts on the default path. Commit first, review every shell command it proposes, and keep a
GEMINI.mddenylist of commands it must never execute.
For most developers in 2026, Gemini CLI is worth installing for one specific reason: it gives you a capable, large-context coding agent at no cost, which makes it the obvious tool for exploratory work, codebase Q&A, and any task where holding a lot of files in context matters more than surgical edits. Pair it with a more precise agent for the edits you'll ship, and you get most of the benefit of paid tooling for free.
Originally published at pickuma.com. Subscribe to the RSS or follow @pickuma.bsky.social for new reviews.
Top comments (0)