gemini-cli

Provides a terminal-based REPL that maintains multi-turn conversation state with Google's Gemini models via streaming API responses. The system implements turn-based processing with automatic context management, handling both user input buffering and incremental token streaming from the Gemini API. Uses a state machine architecture to manage conversation lifecycle, including session persistence and chat compression for context window optimization.

Dynamically discovers, loads, and manages MCP servers as external tool providers, allowing the agent to extend its capabilities beyond built-in tools. The system implements a tool registry that communicates with MCP servers via stdio or HTTP transports, automatically discovering available tools and marshaling arguments/responses through the MCP protocol. Supports both local MCP servers and remote endpoints with configurable lifecycle management.

Automatically compresses conversation history when approaching the Gemini model's context window limit by summarizing older turns and removing redundant information. The system implements a compression strategy that identifies important context (tool results, key decisions) and summarizes conversational turns, maintaining semantic meaning while reducing token count. Compression is transparent to the user and happens automatically during turn processing.

Provides an extension mechanism that allows users to define custom hooks at various points in the agent lifecycle (pre-prompt, post-response, tool-execution) and inject configuration variables. Extensions are JavaScript/TypeScript modules that can modify prompts, intercept tool calls, and customize behavior without modifying core code. The system implements a hook registry and variable interpolation system that processes extensions during initialization.

Provides a browser automation capability that allows the agent to navigate websites, extract content, and interact with web pages. The system implements a headless browser controller (likely using Puppeteer or similar) that can be invoked as a tool, enabling the agent to research information, verify web content, and interact with web-based services. Browser sessions are managed with configurable timeouts and resource limits.

Collects structured telemetry data about agent execution including API call metrics, tool execution times, token usage, and error rates. The system implements a telemetry pipeline that logs events in structured format (JSON), tracks performance metrics, and can export data to external observability platforms. Telemetry is configurable and can be disabled for privacy-sensitive deployments.

Implements a server protocol that allows Gemini CLI agents to communicate with other agents via HTTP/gRPC, enabling distributed agent systems and agent-to-agent delegation. The system provides an A2A server that exposes agent capabilities as remote endpoints, allowing other agents to invoke tools and request assistance. Uses a standardized protocol for agent discovery, capability advertisement, and request/response handling.

Implements a multi-layered security system that gates tool execution through approval workflows, sandboxing, and permission policies. The system evaluates tool calls against security rules before execution, can require user approval for sensitive operations, and isolates shell command execution in macOS sandbox environments with configurable permission levels (restrictive, permissive, open). Uses a security approval system that intercepts tool calls and enforces policies based on tool type and operation.

Allows users to reference local files in prompts using @-syntax (e.g., @./src/main.ts), which automatically reads and injects file contents into the conversation context. The system implements a file resolver that parses @-references, validates file paths, reads file contents, and includes them in the prompt sent to Gemini. Supports glob patterns and directory references for batch file inclusion, with automatic syntax highlighting detection based on file extensions.

Provides a /shell command that executes arbitrary shell commands in the user's environment and captures their output for inclusion in the conversation. The system spawns a child process, streams stdout/stderr back to the REPL, and includes the command output in the next Gemini API call. Supports both interactive shell sessions and non-interactive command execution with configurable working directories and environment variables.

Supports non-interactive mode via the -p flag, allowing users to pipe prompts via stdin and capture AI responses via stdout. The system reads the entire prompt from stdin, sends it to Gemini, and streams the response to stdout without entering the REPL. Enables integration with shell scripts, CI/CD pipelines, and command-line tool chains where interactive mode is not feasible.

Provides configurable model routing that allows users to select between Gemini API, Vertex AI, and local models (via Ollama or similar). The system maintains a model registry with provider-specific configurations, supports dynamic model switching during conversations, and implements fallback logic when primary models are unavailable. Uses a provider abstraction layer that normalizes API calls across different LLM providers.

Allows definition of reusable agent skills and sub-agents that can be invoked by the main agent for specialized task execution. The system implements a skill registry where each skill is a pre-configured agent with specific instructions, tools, and capabilities. Sub-agents can be invoked via tool calls, enabling hierarchical task decomposition where complex problems are delegated to specialized agents.

Manages conversation sessions with automatic persistence to disk, allowing users to save, load, and resume conversations across terminal sessions. The system stores conversation history, tool execution results, and session metadata in a structured format, implements session listing and search capabilities, and supports session export in multiple formats. Uses a session store abstraction that can be backed by local files or external storage.

Provides a VS Code extension that integrates Gemini CLI capabilities directly into the editor, enabling inline code generation, refactoring suggestions, and conversational assistance without leaving the IDE. The system implements a bidirectional sync between the editor and CLI, allowing code selections to be sent to the agent and responses to be inserted back into the editor. Uses the VS Code extension API for editor integration and a local communication protocol for CLI sync.