gemini-cli/docs/codebase_understanding.md

Codebase understanding

This document provides a detailed overview of the Gemini CLI architecture, its core components, and how they interact to provide an agentic terminal experience.

Repository overview

Gemini CLI is structured as a monorepo using npm workspaces. The codebase is divided into several specialized packages that separate the user interface from the agentic orchestration logic.

Core packages

• packages/cli: Contains the terminal user interface (TUI) implemented with React and Ink. It handles terminal-specific logic like keybindings, mouse events, and layout rendering.
• packages/core: The central engine of the application. It is UI-agnostic and manages the Gemini API communication, tool orchestration, conversation history, and policy enforcement.
• packages/devtools: Provides a developer-focused inspector (similar to Chrome DevTools) for monitoring network traffic and console logs in real-time.
• packages/sdk: A library for building extensions and custom tools that integrate with Gemini CLI.
• packages/vscode-ide-companion: A VS Code extension that connects the editor state to the CLI, enabling the agent to read open files and cursor positions.

Application lifecycle

The application follows a structured startup and execution flow to ensure security and environment consistency.

Startup and sandboxing

When you launch Gemini CLI, the entry point in packages/cli/src/gemini.tsx manages several initialization steps:

1. Configuration loading: Loads user and workspace settings, parsing command-line arguments.
2. Authentication: Validates credentials and refreshes OAuth tokens.
3. Sandboxing: If configured, the application relaunches itself in a restricted child process using a "sandbox" environment to isolate tool execution.
4. Mode selection: Determines whether to start the interactive TUI or run in non-interactive mode based on input and terminal state.

Interactive vs. non-interactive modes

• Interactive mode: Renders the TUI using Ink. The state is managed via React contexts (Settings, Mouse, Keypress, Terminal) and a central AppContainer.
• Non-interactive mode: Executes a single prompt or command. It uses a focused loop in packages/cli/src/nonInteractiveCli.ts that continues until the agent completes its task or requires user intervention that cannot be provided.

Agent orchestration

The orchestration of the agent's behavior happens primarily within packages/core/src/core.

GeminiClient

The GeminiClient is the primary interface for the rest of the application. It coordinates:

• Session management: Initializing, resuming, and persisting chat sessions.
• Model routing: Deciding which Gemini model to use based on the task and configuration.
• Context compression: Summarizing long histories using the ChatCompressionService to stay within context window limits.
• IDE integration: Injecting editor context (open files, selections) into the prompt.

GeminiChat and Turn

• GeminiChat: Manages the low-level API communication. It handles streaming responses, retries for transient network errors, and records the conversation history.
• Turn: Represents a single agentic exchange. A turn may involve multiple API calls if the model decides to use tools. It yields events for content, thoughts, and tool requests.

Tool system and scheduler

The tool system allows the agent to interact with the external world. It is built on a secure, policy-driven framework.

Tool registry

The ToolRegistry in packages/core/src/tools maintains a list of all available tools. It supports several types:

• Built-in tools: Native TypeScript implementations for file system operations, shell commands, and web fetching.
• Discovered tools: Local scripts or commands identified in the project root.
• MCP tools: Tools provided by external servers via the Model Context Protocol.

Scheduler

The Scheduler in packages/core/src/scheduler manages the lifecycle of a tool call:

1. Validation: Ensures the tool exists and the arguments match the schema.
2. Policy check: Consults the Policy Engine to determine if the tool is allowed to run automatically, requires user confirmation, or is denied.
3. Confirmation: If required, it pauses execution and uses the MessageBus to request user approval through the UI.
4. Execution: Runs the tool and captures the output, including live updates for long-running processes.
5. Feedback: Sends the tool result back to the model to continue the agentic loop.

UI architecture

The UI is built with React components rendered to the terminal via Ink. Key design patterns include:

• Providers: Global state like settings, theme, and terminal size is provided through React Contexts to avoid prop drilling.
• Console patching: Standard console.log calls are intercepted and redirected to the TUI's debug console or the devtools server.
• Event-driven updates: The UI listens to coreEvents from the orchestrator to update its state (e.g., streaming text, tool progress, or errors).

Testing and quality

The project maintains high standards through several testing tiers:

• Unit tests: Located alongside the source code (e.g., *.test.ts), using Vitest.
• Integration tests: E2E tests in the integration-tests/ directory that run the compiled CLI against mocked and real API endpoints.
• Evals: Specialized evaluation scripts in evals/ that measure the agent's performance on specific tasks like tool use and codebase navigation.