Skip to content
/

Gemini CLI (Google)

gemini-cli · google-gemini/gemini-cli · ★ 105k · last commit 2026-05-24

Primitive shape 24 total
Commands 11 Skills 13
00

Summary

Gemini CLI — Summary

Google's official open-source CLI agent for the Gemini model family, built as a TypeScript/React (Ink) monorepo with Node.js runtime, that brings Gemini directly into the terminal. It ships a full interactive TUI powered by Ink, a VS Code companion extension, an A2A (Agent-to-Agent) server, and an embedded developer tools panel (network/console inspector). The .gemini/ directory carries 11 slash-command .toml files and 13 skill directories (each with a SKILL.md), following the same YAML-frontmatter skill format as Codex CLI. Gemini CLI differentiates by offering a generous free tier (60 req/min, 1000 req/day via personal Google account), built-in Google Search grounding, conversation checkpointing, and a VS Code IDE companion — making it the most complete "bring Gemini to your workflow" baseline in this batch.

Compared to seeds: architecturally closest to openspec (parallel commands + skills, no hooks), but unlike openspec it is a full agent runtime rather than a methodology pack. It is Google's counterpart to OpenAI Codex CLI — both serve as vendor-baseline comparisons.

01

Overview

Gemini CLI — Overview

Origin

Launched by Google in 2025 as the open-source CLI client for the Gemini API. Repository: google-gemini/gemini-cli. Apache 2.0 license. 104K+ stars as of analysis.

Philosophy

Terminal-first, extensible, and free-tier accessible. From GEMINI.md:

"Gemini CLI is an open-source AI agent that brings the power of Gemini directly into the terminal. It is designed to be a terminal-first, extensible, and powerful tool for developers."

Key design values:

  • Free tier first: 60 req/min + 1000 req/day without billing
  • 1M token context: leverages Gemini's large context window
  • Google Search grounding: real-time information built in
  • Extensible via MCP: plug in any MCP server for custom tools
  • Conventional Commits: strict commit discipline enforced via contributor guidelines

Manifesto-style quotes (from GEMINI.md)

"Always activate the pr-creator skill for PR generation, even when using the gh CLI."

"Always use the docs-writer skill when you are asked to write, edit, or review any documentation."

"Keep PRs small, focused, and linked to an existing issue."

"For simple, non-code changes like documentation or prompting updates, skip preflight at the end of the task and wait for PR validation."

Distribution

  • npx @google/gemini-cli (zero-install run)
  • npm install -g @google/gemini-cli
  • brew install gemini-cli
  • sudo port install gemini-cli (MacPorts)
  • Conda environment support
  • Release channels: nightly (daily), preview (weekly Tuesdays), stable/latest (weekly Tuesdays)

Target Users

Developers wanting Gemini in the terminal with a free tier, Google Search grounding, and extensibility via MCP.

02

Architecture

Gemini CLI — Architecture

Distribution & Install

  • npm install -g @google/gemini-cli (npm global)
  • npx @google/gemini-cli (zero-install)
  • brew install gemini-cli
  • Build from source: npm install && npm run build:all

Required Runtime

  • Node.js >= 20.0.0 (recommended ~20.19.0)
  • TypeScript (compiled; not required at runtime)

Monorepo Structure

google-gemini/gemini-cli/
├── packages/
│   ├── cli/           # Terminal UI (React + Ink), input processing, display rendering
│   ├── core/          # Gemini API orchestration, prompt construction, tool execution
│   ├── a2a-server/    # Experimental Agent-to-Agent server
│   ├── sdk/           # Programmatic SDK for embedding capabilities
│   ├── devtools/      # Integrated developer tools (Network/Console inspector)
│   ├── test-utils/    # Shared test utilities
│   └── vscode-ide-companion/  # VS Code extension
├── .gemini/
│   ├── commands/      # 11 .toml command files + 1 github/ subdir + 1 oncall/ subdir
│   │   ├── code-guide.toml
│   │   ├── core.toml       # Injects full packages/core source into context
│   │   ├── find-docs.toml
│   │   ├── frontend.toml
│   │   ├── full-context.toml
│   │   ├── github/
│   │   ├── introspect.toml
│   │   ├── oncall/
│   │   ├── prompt-suggest.toml
│   │   ├── review-and-fix.toml
│   │   ├── review-frontend.toml
│   │   └── strict-development-rules.md
│   ├── skills/        # 13 skill directories, each with SKILL.md
│   │   ├── agent-tui/
│   │   ├── async-pr-review/
│   │   ├── behavioral-evals/
│   │   ├── ci/
│   │   ├── code-reviewer/
│   │   ├── docs-changelog/
│   │   ├── docs-writer/
│   │   ├── github-issue-creator/
│   │   ├── pr-address-comments/
│   │   ├── pr-creator/
│   │   ├── review-duplication/
│   │   ├── string-reviewer/
│   │   └── tui-tester/
│   ├── config.yaml
│   └── settings.json  # Experimental feature flags (voiceMode, autoMemory, ADK, etc.)
├── GEMINI.md          # Project context file (like CLAUDE.md for Claude Code)
├── docs/              # User documentation
├── evals/             # Evaluation suite
├── integration-tests/
├── memory-tests/
└── perf-tests/

Target AI Tools

  • Gemini API (primary: Gemini 3 Pro / Gemini 2.5)
  • Free tier: Google personal account (60 req/min, 1000 req/day)
  • OAuth login via Google account or API key
  • GitHub integration via gemini-cli GitHub Action
03

Components

Gemini CLI — Components

Commands (.gemini/commands/ — 11 .toml files + subdirs)

Command Purpose
code-guide.toml Injects package code-guide context into prompt
core.toml Injects full packages/core source tree into context (code understanding)
find-docs.toml Locates and surfaces documentation
frontend.toml Frontend-specific context and guidelines
full-context.toml Injects complete project context
github/ GitHub-related commands (subdirectory)
introspect.toml Agent self-inspection commands
oncall/ On-call workflow commands (subdirectory)
prompt-suggest.toml Suggests improved prompts
review-and-fix.toml Review code and apply fixes
review-frontend.toml Frontend-specific code review
strict-development-rules.md Markdown command with strict dev constraints

Skills (.gemini/skills/ — 13 directories, each with SKILL.md)

Skill Purpose
agent-tui TUI agent testing and automation
async-pr-review Asynchronous PR review workflow
behavioral-evals Run behavioral evaluations
ci CI pipeline interaction and monitoring
code-reviewer Code review execution
docs-changelog Generate/update changelog from commits
docs-writer Write or edit documentation (required for all doc tasks)
github-issue-creator Create GitHub issues with proper formatting
pr-address-comments Address PR review comments
pr-creator Create PRs following repo template standards (required for all PRs)
review-duplication Identify code duplication
string-reviewer Review user-facing strings for quality
tui-tester Test TUI components and interactions

Packages (npm workspace packages)

Package Purpose
@google/gemini-cli CLI binary entry point
@google/gemini-cli-core Backend logic, API orchestration, tool execution
@google/gemini-cli-sdk Programmatic embedding SDK
a2a-server Experimental Agent-to-Agent protocol server
devtools Network + Console inspector panel
vscode-ide-companion VS Code extension
test-utils Shared test utilities

Settings (.gemini/settings.json)

Experimental feature flags:

{
  "experimental": {
    "extensionReloading": true,
    "modelSteering": true,
    "autoMemory": true,
    "topicUpdateNarration": true,
    "voiceMode": true,
    "adk": { "agentSessionNoninteractiveEnabled": true }
  },
  "general": { "devtools": true }
}

Built-in Tools

  • File operations (read, write, edit)
  • Shell command execution
  • Google Search grounding
  • Web fetching
  • MCP server integration (extensible)
05

Prompts

Gemini CLI — Prompts

Prompt File Formats

Two formats used:

  1. TOML commands (.gemini/commands/): description + prompt fields; supports {{args}} placeholders and !{...} shell interpolations
  2. SKILL.md (.gemini/skills/): YAML front-matter + Markdown body (identical format to Codex CLI skills)

Verbatim Excerpt 1: core.toml command (context injection pattern)

File: .gemini/commands/core.toml

description="Injects context of all relevant cli files"
prompt = """
The following output contains the complete
source code of packages/core.
**Pay extremely close attention to these files.** They define the project's
core architecture, component patterns, and testing standards.

The source code contains the content of absolutely every source code file in
packages/core.
You should very rarely need to read any other files from packages/core to resolve
prompts.

!{find packages/core \( -path packages/cli/dist -o -path packages/core/dist -o -name node_modules \) -prune -o -type f \( -name "*.ts" -o -name "*.tsx" \) ! -name "*.test.ts" ! -name "*.test.tsx" ! -name "*.d.ts" -exec echo "--- {} ---" \; -exec cat {} \;}

In addition to the code context, you MUST strictly adhere to the following frontend-specific development guidelines when writing code in packages/core.
...
{{args}}. 
"""

Prompting technique: Shell-interpolation context injection (!{...}) — the entire source tree is concatenated into the prompt at invocation time. Bold emphasis on "Pay extremely close attention" forces priority. {{args}} is the user's task appended after the context dump.

Verbatim Excerpt 2: pr-creator skill (process enforcement)

File: .gemini/skills/pr-creator/SKILL.md (partial)

---
name: pr-creator
description:
  Use this skill when asked to create a pull request (PR). It ensures all PRs
  follow the repository's established templates and standards.
---

# Pull Request Creator

## Workflow

1. **Branch Management**: **CRITICAL:** Ensure you are NOT working on the `main` branch.
   - Run `git branch --show-current`.
   - If the current branch is `main`, you MUST create and switch to a new descriptive branch.

2. **Commit Changes**: Verify that all intended changes are committed. NEVER commit directly to `main`.

6. **Preflight Check**: Before creating the PR, run the workspace preflight script:
   ```bash
   npm run preflight

Principles

  • Safety First: NEVER push to main. This is your highest priority.
  • Compliance: Never ignore the PR template. It exists for a reason.
  • Accuracy: Don't check boxes for tasks you haven't done.

**Prompting technique**: Imperative checklist with CRITICAL and NEVER keywords as iron-law constraints. Safety rail (branch check) is step 1. Principles section reiterates the top constraint in a separate section for emphasis — similar to superpowers' "Iron Law" pattern but in a skill rather than a session hook.

## GEMINI.md (project context file)

The `GEMINI.md` file functions like Claude Code's `CLAUDE.md` — it is automatically injected at session start to provide project context, conventions, and skill-invocation mandates.
09

Uniqueness

Gemini CLI — Uniqueness & Positioning

Differs from Seeds

Gemini CLI is the Google counterpart to OpenAI's Codex CLI — both are vendor-owned, full-runtime CLI agents. Unlike all 11 seed frameworks (which augment existing AI tools like Claude Code or provide methodology docs), Gemini CLI is a self-contained runtime. It is most similar in component structure to openspec (parallel commands + skills pattern) but is a complete agent rather than a prompt methodology. The strongest architectural delta from seeds: (1) built-in Google Search grounding as a first-class tool (no seed has this); (2) A2A protocol server enabling other agents to call Gemini CLI (no seed has agent-to-agent protocol); (3) VS Code IDE companion is a separate package (unlike kiro which is a full IDE fork); (4) the !{shell} interpolation in TOML commands enables dynamic context injection at invocation time — a pattern not seen in any seed.

Positioning

The "official Google answer" to locally-run Gemini development. The free tier (1000 req/day) makes it the most accessible entry point in the batch for developers who want a capable LLM without billing setup.

Key Differentiators

  1. Free tier by default — 1000 req/day via personal Google account
  2. Google Search grounding — real-time information as a built-in tool
  3. A2A server — acts as both A2A client and server (experimental)
  4. 1M token context window — reduces need for complex compaction strategies
  5. Shell interpolation in commands (!{find ...}) — dynamically injects live filesystem state into prompts
  6. Mandatory skill invocation rules — GEMINI.md mandates specific skills for PR/doc tasks, enforcing process compliance
  7. GitHub Action first-class — official GitHub Action for CI/CD integration

Observable Failure Modes

  • No sandboxing: unlike Codex CLI, all commands run in the user's live environment; risk of accidental destructive operations
  • Free tier rate limits: 60 req/min cap can cause workflow interruptions on large tasks
  • Experimental features: autoMemory, modelSteering, voiceMode, A2A server are all experimental — production stability unknown
  • Mandatory skill usage can feel rigid: GEMINI.md requires pr-creator even for simple PRs
  • preflight is slow: GEMINI.md explicitly warns it has "long runtime" — creates friction in rapid iteration
04

Workflow

Gemini CLI — Workflow

Execution Modes

Mode Trigger Description
Interactive TUI gemini React/Ink terminal UI; conversation loop with tool approvals
Non-interactive scripted --print or pipe Single-shot output for automation
GitHub Action run-gemini-cli action PR review, issue triage, on-demand via @gemini-cli mention
Conversation checkpoint built-in Save and resume complex sessions

Typical Workflow

Phase Action Artifact
Auth OAuth login or API key setup Saved credential
Context loading GEMINI.md read + command context injection System prompt
Skill or command User invokes /skill-name or uses slash command Skill instructions loaded
Task execution Agent uses read/write/bash/search tools File edits, shell output
Approval User confirms or rejects tool calls Approved action
PR creation Always via pr-creator skill PR with template compliance
Doc writing Always via docs-writer skill Updated docs

Enforced Workflow Rules (from GEMINI.md)

  1. PR creation: always activate pr-creator skill, even when using gh CLI
  2. Documentation: always use docs-writer skill for any doc task
  3. Commits: follow Conventional Commits standard
  4. Quality: run npm run preflight before PR submission (skip for doc-only changes)
  5. Branch safety: never commit to main; always create a descriptive branch first

Approval Gates

  1. Tool call confirmation — each shell/file operation shown with [Y/n] prompt
  2. npm run preflight — build + lint + typecheck + tests before PR (manual gate)
  3. PR review — external reviewer approval (standard GitHub flow)

Release Workflow

Channel Cadence Quality
nightly Daily UTC 00:00 All changes from main
preview Weekly Tuesday UTC 23:59 Not fully vetted
stable Weekly Tuesday UTC 20:00 Promotion of previous preview
06

Memory Context

Gemini CLI — Memory & Context

Session State

  • Conversation history: in-process linear message list
  • Conversation checkpointing: built-in feature to save and resume complex sessions (per README); exact format unknown
  • GEMINI.md: project-level context file injected at session start (like Claude Code's CLAUDE.md)

Context Files

  • GEMINI.md: read at session start; provides project overview, tech stack, workflow rules, and skill-invocation mandates
  • Commands (.gemini/commands/): injected on explicit invocation; can include entire source trees via !{shell} interpolation
  • Skills (.gemini/skills/): loaded and injected when invoked by name

autoMemory (experimental)

The .gemini/settings.json enables autoMemory: true as an experimental feature. This suggests the CLI can automatically persist facts across sessions, though the exact persistence format is undocumented in public files.

Google Search Grounding

Built-in tool that fetches real-time information via the Gemini API's grounding feature — this is a unique memory augmentation not present in any seed framework.

Cross-Session Handoff

  • Conversation checkpointing allows resume (documented in README)
  • autoMemory experimental feature may persist key facts (format unknown)

Context Compaction

  • No explicit compaction strategy documented
  • The 1M token context window reduces the urgency of compaction vs. smaller-context models

Developer Tools

The devtools package provides a Network/Console inspector panel — useful for observing what context is being sent to the model.

07

Orchestration

Gemini CLI — Orchestration

Multi-Agent Support

Experimental — the a2a-server package implements the Agent-to-Agent (A2A) protocol server. The settings.json includes "adk": { "agentSessionNoninteractiveEnabled": true } and "modelSteering": true, suggesting multi-agent coordination is in development. The async-pr-review skill implies asynchronous agent delegation.

Orchestration Pattern

Sequential (primary interactive loop) with experimental parallel fan-out capability via A2A server. The async-pr-review skill is the clearest indicator of async delegation.

Execution Mode

Interactive loop (primary) + one-shot scripted + event-driven (GitHub Action: PR comments, issue events)

Isolation Mechanism

None built-in — no sandboxing equivalent to Codex CLI's Seatbelt/bwrap. Commands execute directly in the user's shell environment. The GitHub Action runs in GitHub Actions runner isolation.

Multi-Model

  • Single Gemini model per session (model selection via settings)
  • modelSteering experimental flag may enable per-task model routing (undocumented)
  • Supports multiple Gemini model versions (Gemini 3 Pro, Gemini 2.5, etc.)

Prompt Chaining

Yes — commands like core.toml inject the full source tree, then {{args}} appends the user task; the context IS the chained input to the model. Skills chain from GEMINI.md → skill body → task execution.

Consensus Mechanism

None.

GitHub Action Integration

The run-gemini-cli GitHub Action enables:

  • PR reviews triggered by PR events
  • Issue triage triggered by issue events
  • On-demand tasks via @gemini-cli mention in comments
  • Scheduled/custom workflows
08

Ui Cli Surface

Gemini CLI — UI & CLI Surface

Dedicated CLI Binary

  • Binary name: gemini
  • Not a thin wrapper: full agent runtime with TUI, tool execution, Gemini API integration
  • Install: npm install -g @google/gemini-cli or npx @google/gemini-cli

Terminal UI (TUI)

  • Type: terminal-tui
  • Stack: React + Ink (React for CLI rendering)
  • Package: packages/cli/ — "User-facing terminal UI, input processing, and display rendering"
  • Features: conversation display, tool call approvals, streaming output, syntax-highlighted code

VS Code IDE Companion

  • Package: packages/vscode-ide-companion/
  • Type: VS Code extension
  • Purpose: "VS Code extension pairing with the CLI" — extends Gemini CLI capabilities into the VS Code editor

Developer Tools Panel

  • Package: packages/devtools/
  • Description: "Integrated developer tools (Network/Console inspector)"
  • Access: Enabled via .gemini/settings.json "general": { "devtools": true }
  • Features: network request inspection, console message viewing — useful for debugging context injection

GitHub Action

  • Repo: google-github-actions/run-gemini-cli
  • Enables CI/CD integration: PR reviews, issue triage, @gemini-cli mentions, scheduled workflows

Programmatic SDK

  • Package: packages/sdk/
  • Purpose: "Programmatic SDK for embedding Gemini CLI capabilities" in custom applications

A2A Server (experimental)

  • Package: packages/a2a-server/
  • Purpose: "Experimental Agent-to-Agent server" — enables Gemini CLI to act as an A2A-protocol agent that other agents can call

Related frameworks

same archetype · same primary tool · same memory type

Spec Kit ★ 106k

Turns a natural-language feature description into a complete, versioned, AI-executable specification pipeline installable for 30+…

OpenSpec ★ 51k

Adds a lightweight spec layer so AI coding assistants and humans agree on what to build before any code is written.

ECC (Everything Claude Code) ★ 193k

Comprehensive harness-native operator system: 246 skills + 61 agents + continuous learning hooks + multi-model routing across 8…

OpenAI Codex CLI ★ 86k

Give developers a sandboxed, locally-running OpenAI coding agent with approval gates and skill orchestration.

cursorrules v5 (kinopeee) ★ 1.1k

Bilingual (ja/en) Cursor rule set with tricolor task classification, security-first prompt injection defense, and structured git…

windsurfrules v5 (kinopeee) ★ 364

Windsurf/Antigravity port of cursorrules v5 — same tricolor task classification and injection defense, translated to Windsurf's…