HARNESSES AND BROKERS / TERMINAL AGENT

Gemini CLI

Gemini CLI is an Apache 2.0 licensed agent built around one model family. Its open source loop and MCP support make it a readable harness; its tie to Gemini models is the replaceability question to weigh.

Technology

What it is

Gemini CLI is an open source AI agent from Google that runs in a terminal and uses Gemini models. It reads and edits files, runs shell commands, fetches web pages, and can ground answers in Google Search. The project is licensed Apache 2.0 and installs through npm (or runs directly with npx), Homebrew, and other package managers.

It is general purpose rather than strictly a coding agent, though coding is its most common use.

Access, quotas, and models

There are three ways to authenticate: a personal Google account, a Gemini API key, or Vertex AI on Google Cloud. The README lists free-tier limits for a personal Google account of 60 requests per minute and 1,000 requests per day, and describes a 1M token context window for current Gemini models. Quotas change, so treat the README as the authority rather than this page.

The harness is built for Gemini. Choosing Vertex AI over the consumer path changes billing, data handling, and region, not the model family.

Built-in tools and MCP

Built-in tools cover file operations, shell commands, web fetching, and Google Search grounding. For anything else, Gemini CLI connects to MCP servers. Search grounding is a distinctive default: the agent can check a claim against the web rather than answering from model memory, which helps the grounded property for anything outside the repository.

GEMINI.md context files

Project-specific instructions live in GEMINI.md files. The idea is the same as AGENTS.md or CLAUDE.md: conventions written down once, read at the start of each session. When a team runs more than one harness, keeping these files in sync, or pointing them at one shared source, avoids each agent following a different version of the rules.

Extensions, checkpoints, and sandboxing

Custom extensions package commands and integrations for reuse and sharing. Conversation checkpointing saves and resumes long sessions. Sandboxing runs tool execution in a contained environment, which is the setting to check before giving a terminal agent broad shell access.

Scripting and CI

gemini -p runs a prompt non-interactively, with JSON and streaming JSON output formats for scripts. Google also publishes a GitHub Action for running the agent in workflows. As with any headless agent, the permission decisions move into configuration that should be reviewed like code.

Where it fits in an open stack

Gemini CLI is an execution-layer harness with an open source loop and a fixed model family. Its MCP support means tool servers stay portable. Its strongest contribution to an open stack is as a readable reference implementation and an inexpensive way to start, given the free tier.

Gotchas worth knowing

  • Free tier terms are not enterprise terms. Check how prompts and code are handled under each authentication path before using it on restricted work.
  • Shell access needs a boundary. Turn on sandboxing, or run inside a container, before granting broad command execution.
  • Web content is untrusted input. Fetched pages and search results can contain instructions aimed at the agent.
  • Quotas move. Published limits change; automation that assumes a quota will break when it does.

How it scores on openness

  • Replaceable. Weak on models, since it is built for Gemini. Tools over MCP remain replaceable.
  • Inspectable. Strong. Apache 2.0 source.
  • Portable. Moderate. MCP servers move; GEMINI.md content moves if you keep it aligned with other instruction files; extensions are Gemini CLI specific.
  • Bounded. Depends on configuration. Sandboxing exists and should be turned on for broad shell access.
  • Grounded. Good. Repository facts plus optional Google Search grounding.
  • Auditable. Achievable through commits and structured output in headless runs.

What it is not

Gemini CLI is not a model and not a provider-agnostic harness. It is not a broker; it runs one agent.

Openness scorecard for Gemini CLI

The notes above describe the tool. The score belongs to your deployment of it, because configuration, permissions, and where records are kept decide most of the result. Score each test 0 (absent), 1 (partial), or 2 (demonstrated) for the way you run Gemini CLI, out of 12.

TestQuestionWhat a 2 looks likeEvidence to collect
ReplaceableCan one component be swapped without rebuilding the system?A major component has been swapped, and the work was measured in days, not months.Which component did you last swap, and how long did it take?
InspectableCan a builder understand what runs and why?The exact context, tool calls, and results for each step are exported to storage you own.Where do traces live, what do they contain, and how long are they kept?
PortableCan identity, skills, context, and work move?Identity, skills, and work are files in open formats and have been loaded into a second tool.What have you exported and reloaded somewhere else?
BoundedAre authority and approval requirements explicit?Tool scopes, delegated user identity, and approvals are enforced outside the model and tested adversarially.What stops the agent from taking an action its user could not take?
GroundedDo agents share durable data and semantic meaning?Agents query governed metrics over versioned tables and cite the definition and data version.Which semantic definitions and tables do agents use?
AuditableCan people reconstruct decisions and outcomes?Runs, approvals, and data versions are recorded long enough to reconstruct any decision.Could you reconstruct an agent decision from three months ago?

Score your Gemini CLI setup on the interactive scorecard. It runs in your browser, and you can download the result as JSON or print it.

Where to learn more

Primary sources first. Documentation and specifications move faster than any summary, so treat the links below as the authority and this page as orientation.

Work with Alex