gemini-cli

Provides a terminal-based read-eval-print loop that maintains stateful conversation history with Google's Gemini API, supporting streaming responses and turn-based message processing. The system implements a UI state machine that handles input buffering, command parsing, and response rendering while managing chat compression to keep context within token limits. Streaming is handled via the Gemini API's server-sent events, with responses progressively rendered to the terminal as tokens arrive.

Dynamically discovers, connects to, and manages Model Context Protocol (MCP) servers as external tool providers, allowing the Gemini agent to execute tools defined by third-party MCP servers. The system maintains a registry of available MCP servers, handles their lifecycle (startup, shutdown, reconnection), and translates tool schemas from MCP format into Gemini function-calling format. Tool execution results are streamed back through the MCP protocol and integrated into the conversation flow.

Provides a plugin architecture for extending Gemini CLI with custom functionality through extensions that can define new tools, commands, and behaviors. Extensions are configured via settings and can access configuration variables, hooks, and the core agent API. The system supports extension lifecycle management (initialization, cleanup) and allows extensions to register custom tools that are exposed to the Gemini agent.

Provides a VS Code extension (vscode-ide-companion) that integrates Gemini CLI with the IDE, allowing users to invoke the agent from within the editor and use editor context (selected code, file paths, project structure) as input to the agent. The integration supports inline code generation, refactoring suggestions, and documentation generation directly in the editor. The VS Code extension communicates with the Gemini CLI backend via a local API.

Implements a browser agent that can navigate websites, extract information, and interact with web pages on behalf of the user. The agent uses browser automation (likely Puppeteer or similar) to control a headless browser, take screenshots, extract text content, and fill forms. Browser interactions are exposed as tools that the Gemini agent can invoke, allowing it to research information, fill out web forms, or automate web-based tasks.

Implements comprehensive telemetry and observability features that track agent execution, tool calls, API usage, and performance metrics. The system logs structured events (JSON format) that can be exported to external observability platforms (e.g., Google Cloud Logging, Datadog). Telemetry includes latency measurements, token usage, tool execution results, and error tracking. Users can configure telemetry verbosity and choose which events to export.

Manages agent sessions that persist conversation history, state, and configuration across multiple invocations. Sessions are stored locally (or optionally in external storage) and can be resumed, forked, or archived. The system supports session metadata (creation time, last modified, tags) and allows filtering/searching sessions. Session management enables long-lived agent interactions where context is preserved across terminal sessions.

Provides a hooks system that allows extensions and configurations to inject custom logic at key points in the agent lifecycle (initialization, prompt generation, tool execution, response processing). Hooks are registered by extensions or configuration and are called at specific events, allowing customization without modifying core code. The system supports pre-hooks (before an action) and post-hooks (after an action) for most major operations.

Implements a security approval system that intercepts tool calls before execution, allowing users to review and approve/deny sensitive operations like shell commands, file writes, and API calls. The system maintains approval policies (per-tool, per-pattern, or blanket approvals) and can sandbox execution environments on macOS using Security Framework policies. Approval decisions are logged and can be configured to require interactive confirmation or auto-approve trusted patterns.

Executes arbitrary shell commands in the user's environment and captures their output (stdout/stderr) in real-time, streaming results back to the Gemini agent for analysis and follow-up actions. The system runs commands in the user's current shell context, preserving environment variables and working directory, and can handle long-running processes with progressive output streaming. Command execution is subject to the security approval system before running.

Provides file read, write, and directory operations through a tool system that supports @-syntax for referencing files in prompts, allowing users to include file contents directly in the conversation context. The system can read entire files or specific line ranges, write new files or append to existing ones, and list directory contents. File operations are integrated into the tool execution pipeline and subject to security approval.

Supports running Gemini CLI in non-interactive mode via the -p flag, executing a single prompt and returning results without entering the REPL. This mode is designed for scripting and automation, where the CLI is invoked as a subprocess with a prompt and returns structured output. The system processes the prompt through the full agent pipeline (tool execution, streaming, etc.) and exits after completion, making it suitable for shell scripts and CI/CD pipelines.

Allows defining reusable agent skills that encapsulate multi-step workflows and can be invoked by the main agent or other sub-agents. Skills are defined as specialized agents with their own system prompts, tool access, and capabilities, enabling hierarchical task decomposition. The system supports agent-to-agent (A2A) communication via the A2A Server, allowing sub-agents to be spawned dynamically and managed as part of the main agent's execution flow.

Supports routing prompts to different Gemini models (e.g., gemini-2.0-flash, gemini-1.5-pro) based on configuration, task complexity, or cost optimization. The system can be configured to use different models for different types of tasks or to fall back to alternative models if the primary model is unavailable. Model routing is configured via settings and can be overridden per-prompt or per-session.

Automatically compresses conversation history to stay within Gemini API token limits while preserving semantic meaning. The system uses a compression algorithm that summarizes older turns and removes redundant information, allowing long conversations to continue without hitting context limits. Compression is triggered automatically when approaching token limits and can be configured with different compression strategies.

Generates and manages system prompts that define the agent's behavior, capabilities, and constraints. The system prompt is constructed from multiple sources: base prompts, tool descriptions, extension configurations, and user customizations. The system can generate different prompts for different contexts (interactive vs. non-interactive, different model versions) and supports hooks for customizing prompt generation.