Gemini CLI Tools: A Curator’s Index

The Gemini CLI Tooling Landscape

Gemini CLI is built around four extension surfaces, each with a different scope and lifecycle. The official repository ships with a core agent loop that delegates tool invocations to three subsystems: a built-in shell executor, a file-system reader/writer, and an MCP client. That client is the gateway to the community ecosystem. Everything installed via the mcpServers key in ~/.gemini/settings.json participates in the same tool-dispatch mechanism.

The Model Context Protocol specification (2025-11-25) defines three transport modes — stdio, SSE, and Streamable HTTP — and Gemini CLI supports all three. In practice, the community leans heavily on stdio for local servers and SSE for Docker-based servers. Of the four configuration failure classes tracked across open GitHub issues, transport mismatch is the most common root cause: a server declared as HTTP but launched as a stdio process produces the “missing httpUrl” error seen in issue #14621.

Config templates (GEMINI.md files) sit at a different layer: they inject natural-language instructions into context before any tool is called, shaping how the model interprets tool output. Shell scripts operate outside the agent loop entirely — they orchestrate the CLI as a subprocess and are therefore reproducible across CI environments. The VS Code Companion extension bridges the terminal agent into the IDE diff view. Each layer is independently useful and they compose cleanly; understanding where each one starts and stops is the key to building reliable workflows.

# Minimal ~/.gemini/settings.json skeleton
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_TOKEN" }
    }
  }
}

MCP Servers: Community Ecosystem Synthesis

After scanning the open issues on the google-gemini/gemini-cli repository, four distinct MCP connectivity failure modes account for the bulk of reported problems. Of tracked MCP-related issues filed between July and December 2025:

• Transport misconfiguration — declaring HTTP transport but running a stdio server (#14621, #15551)
• PATH resolution failures on macOS — npx not found because the shell launched by Gemini CLI does not inherit the user's PATH (#3406)
• Network fetch failures — SSE servers returning “fetch failed” on cold start before the server is fully listening (#10051)
• Windows config-detection failures — settings.json correctly written but /mcp reports “No MCP servers configured” due to path separators (#4675)

The official MCP server integration docs recommend always specifying absolute paths in the command field on macOS and Windows to sidestep PATH inheritance. For stdio servers, prepend npx with the full Node path (e.g., /usr/local/bin/npx) or use the Docker transport as a portable alternative. The GitHub-maintained github-mcp-server installation guide for Gemini CLI demonstrates the Docker pattern as the most reliable cross-platform approach.

The official MCP Registry lists hundreds of published servers. Community-curated aggregators like mcpservers.org track Gemini-CLI-specific entries. The highest-adoption servers in the Gemini CLI context remain GitHub (code search, PR management), filesystem (project-wide refactors), and Brave/Fetch (web grounding). Each server requires a token or API key configured via the env field in settings.json.

# Verify MCP server connection after configuration
$ gemini mcp list
# Should print the server name and its available tools.
# If it prints "No MCP servers configured", check:
#   1. settings.json is at ~/.gemini/settings.json (not .gemini/settings.json)
#   2. The command field uses an absolute path
#   3. Run: echo $PATH  — then hard-code that path in "command"

Config Templates: What Works Across Stacks

GEMINI.md files are the primary mechanism for injecting persistent, project-aware context into every Gemini CLI session. The official documentation defines a three-level hierarchy: a global file at ~/.gemini/GEMINI.md for preferences that span all projects, a project-root file for repository-wide conventions, and subdirectory files for module-specific rules. The CLI concatenates them in order from most general to most specific; the /memory show command prints the resolved context so you can verify what the model actually receives.

A Google Cloud Community analysis of context bloat in GEMINI.md files documented that teams frequently over-stuff the root GEMINI.md with exhaustive documentation, causing the model to receive more irrelevant context than actionable instructions. The recommended pattern — confirmed independently by the gemini-cli-tips repository maintained by Addy Osmani — is to use the @file.md import syntax to split large instructions into focused sub-files and import only what is relevant at each directory level.

Across the community templates indexed here, three structural patterns repeat most often: a “persona + constraints” block at the top (who the model is and what it must never do), a “stack context” block (language versions, framework conventions), and a “workflow rules” block (commit message format, test requirements). Negative constraints (“Do not use class components”) consistently outperform positive instructions (“Use functional components”) for enforcing coding style.

# Minimal GEMINI.md template for a TypeScript monorepo
## Persona
You are a senior TypeScript engineer on this repo. Never use `any`.

## Stack
- Node 20 LTS, TypeScript 5.4, pnpm workspaces
- Do not introduce new top-level dependencies without asking

## Workflow
- Commit messages: Conventional Commits (feat/fix/chore/docs)
- All new functions must have JSDoc with @param and @returns
- Do not edit files outside the package you are asked about

# Check resolved context at any time:
$ gemini -p "/memory show"

The everything-gemini-code repository provides production-ready GEMINI.md templates for several stack profiles alongside MCP configurations, making it one of the more complete community starting points for teams adopting Gemini CLI at scale.

Shell Scripts: The Productivity Layer

Shell scripts that wrap Gemini CLI give teams reproducible, CI-safe automation without requiring any MCP infrastructure. Because Gemini CLI accepts a prompt via the -p flag and reads from stdin, every common developer workflow can be reduced to a one-liner or a short script. The official shell tool documentation explains how the built-in run_shell_command tool supports pseudo-terminal (pty) mode for interactive commands alongside the standard non-interactive pipe mode used in scripts.

The most commonly referenced script patterns in the community cover: automated commit-message generation from git diff --staged, PR description drafting from branch diff, test-failure triage from CI log output, log summarization for incident response, and security-finding explanation from static analysis output. The dev.to guide “7 Insane Gemini CLI Tips” covers several of these automation patterns with concrete examples.

#!/usr/bin/env bash
# git-commit-ai.sh — generate a commit message from staged diff
# Usage: git add <files> && ./git-commit-ai.sh

DIFF=$(git diff --staged)
if [ -z "$DIFF" ]; then
  echo "No staged changes." && exit 1
fi

MSG=$(echo "$DIFF" | gemini -p "Write a Conventional Commits message for this diff.
Output only the commit message, no explanation.")

echo "Proposed message:"
echo "$MSG"
read -p "Accept? (y/n) " CONFIRM
if [ "$CONFIRM" = "y" ]; then
  git commit -m "$MSG"
fi

The shell integration also supports the --output_format json flag for scripts that need structured output to pipe into further processing. A shell-autocompletion feature for bash, zsh, and fish was requested in issue #1855 and remains open as of the time of writing, meaning tab-completion for CLI flags must currently be configured manually.

VS Code Extension: Editor Integration

The Gemini CLI Companion extension (publisher: Google, VS Code Marketplace ID Google.gemini-cli-vscode-ide-companion) bridges the terminal agent into the IDE by exposing real-time workspace context — open files, cursor position, and text selection — to Gemini CLI running in the integrated terminal. Suggested changes trigger a native VS Code diff view with in-diff editing before acceptance, replacing the raw file-overwrite experience of using the CLI in a standalone terminal.

The official IDE integration documentation notes that the extension is also published on the Open VSX Registry for VS Code forks such as VSCodium and Cursor. Installation is a prerequisite for the companion detection feature; without it, Gemini CLI operates without IDE context.

A notable community-reported friction point: issue #18961 documents cases where Gemini CLI fails to detect the companion extension even after it is correctly installed, reporting “IDE companion not found” in CLI output. The root cause traced to Gemini CLI launching before the VS Code extension host had fully initialised. The workaround is to open the integrated terminal after VS Code has fully loaded (not immediately on window open).

# Verify companion extension is detected
$ gemini
# In the Gemini CLI session, run:
/status
# Look for: "IDE: VS Code Companion (connected)"
# If you see "IDE: not connected":
#   1. Reload VS Code window (Cmd/Ctrl+Shift+P → "Reload Window")
#   2. Open a NEW integrated terminal after reload
#   3. Re-run gemini

How to Choose: A Decision Framework

Based on the failure patterns and community workflows synthesised above, the evidence points to a clear layering strategy:

• Start with a GEMINI.md template — zero infrastructure, zero configuration errors, immediate improvement in output quality. Every project benefits; it is the highest return-on-effort investment in the tooling stack.
• Add shell scripts for CI/automation — if the workflow needs to run unattended (CI, cron, pre-commit hooks), shell scripts are the only option. MCP servers require a running daemon process and are not suited to ephemeral CI environments without Docker.
• Add MCP servers for external-system integration — when the workflow requires Gemini CLI to query GitHub, search the web, or read a database, an MCP server is the right abstraction. Use the stdio transport with absolute paths to avoid the PATH failures documented in issues #3406 and #4675.
• Add the VS Code Companion for interactive editing — only useful when working interactively in the editor. The diff-review workflow it enables is a meaningful upgrade over reviewing raw file changes, but the companion is strictly a developer-experience layer, not a capability layer.

Teams that try to deploy all four layers simultaneously without first stabilising the GEMINI.md layer tend to generate the most GitHub issues. The community evidence consistently shows that a focused, well-structured context file reduces reliance on complex MCP configurations for many everyday tasks.