Related Pages

Related topics: Agent System, Context and Memory Management

Architecture Overview

Gemini CLI is Google's official command-line interface for Gemini, designed to enable developers to interact with AI models directly from their terminal. The architecture follows a modular, package-based design that separates concerns between the core AI processing engine, the CLI interface, and an optional A2A server component.

Package Structure

The repository is organized into three primary packages under the packages/ directory:

Sources: README.md:1-50

System Architecture

graph TD
    subgraph "CLI Layer (packages/cli)"
        UI[UI Components]
        AUTH[Auth Dialog]
        CMDS[Commands]
        EXT[Extensions]
    end
    
    subgraph "Core Layer (packages/core)"
        AGENTS[Agent System]
        SKILLS[Skills Engine]
        CONTEXT[Context Graph]
        RECORDING[Chat Recording]
    end
    
    subgraph "External"
        GEMINI_API[Gemini API]
        MCP[MCP Servers]
        FS[File System]
    end
    
    UI --> AGENTS
    AUTH --> AGENTS
    CMDS --> AGENTS
    EXT --> AGENTS
    AGENTS --> SKILLS
    AGENTS --> CONTEXT
    AGENTS --> RECORDING
    AGENTS --> GEMINI_API
    SKILLS --> MCP
    SKILLS --> FS
    CONTEXT --> FS

Core Package Architecture

Agents System

The agent system forms the brain of Gemini CLI. The core package implements multiple specialized agents:

#### CLI Help Agent

The CliHelpAgent provides contextual assistance about Gemini CLI features, configuration, and current state. It operates as an expert system that can retrieve internal documentation and provide precise answers.

// Agent configuration and runtime context
const CLI_HELP_AGENT_SYSTEM_PROMPT = `**CLI Help Agent**, an expert on Gemini CLI. Your purpose is to provide accurate information about Gemini CLI's features, configuration, and current state.

### Runtime Context
- **CLI Version:** ${cliVersion}
- **Active Model:** ${activeModel}
- **Today's Date:** ${today}

### Instructions
1. **Explore Documentation**: Use the \`get_internal_docs\` tool to find answers.
2. **Be Precise**: Use the provided runtime context and documentation.
3. **Cite Sources**: Include specific documentation files in your report.
4. **Non-Interactive**: Answer as best you can with available information.

Sources: packages/core/src/agents/cli-help-agent.ts:1-30

#### Skill Extraction Agent

The SkillExtractionAgent enables dynamic skill creation. It processes user interactions and extracts patterns that can be converted into reusable skills. The agent uses a patch-based format for creating skill files:

// Patch format for skill creation
const PATCH_FORMAT = `
1. Update an existing file:

     --- /absolute/path/to/target.md
     +++ /absolute/path/to/target.md
     @@ -<start>,<count> +<newStart>,<newCount> @@
     <unchanged context line>
    -<removed line>
    +<added line>

2. Create a brand-new file (no existing target):

     --- /dev/null
     +++ /absolute/path/to/new-target.md
     @@ -0,0 +1,<count> @@
`;

Sources: packages/core/src/agents/skill-extraction-agent.ts:1-50

Context Graph System

The context graph manages conversation history and session state. It builds a structured representation of the conversation with stable identifiers for each message turn.

graph TD
    subgraph "Context Building"
        HIST[History Array] --> TURN[For Each Turn]
        TURN --> HASH[Generate MD5 Hash]
        HASH --> SALT[Add Turn Salt]
        SALT --> ID[Stable ID Generation]
    end
    
    subgraph "Message Processing"
        MSG[Message] --> ROLE{Message Role}
        ROLE -->|user| USER[User Turn]
        ROLE -->|model| MODEL[Model Turn]
        USER --> PARTS[Process Parts]
        MODEL --> PARTS
    end

Key features of the context graph:

• Stable ID Generation: Uses MD5 hashing combined with turn salt for deterministic message identification
• Legacy Header Handling: Skips legacy environment headers automatically
• Role-based Processing: Differentiates between user and model messages

Sources: packages/core/src/context/graph/toGraph.ts:1-60

Skills Engine

The skills system provides extensible capabilities through a standardized structure:

skill-name/
├── SKILL.md           # Required: Frontmatter + Instructions
├── REFERENCE.md       # Optional: Loaded on demand
├── EXAMPLES.md        # Optional: Common patterns
├── FORMS.md           # Optional: User input forms
├── scripts/           # Executable code (Node.js/Python/Bash)
└── references/        # Domain-specific documentation

#### SKILL.md Structure

Every skill requires a SKILL.md file with YAML frontmatter:

Related Pages

Related topics: Architecture Overview, Tools Reference

Agent System

概述

The Agent System is the core execution engine of Gemini CLI, responsible for orchestrating interactions between Large Language Models (LLMs), tools, and user interactions. It provides a comprehensive framework for managing agent lifecycles, scheduling tasks, executing tools, and maintaining conversation context across sessions.

The agent system is designed with modularity and extensibility in mind, supporting multiple agent types, custom skills, and MCP (Model Context Protocol) server integrations. It handles everything from initial prompt processing to final response delivery, including tool execution, policy enforcement, and checkpoint management.

At its core, the system follows a message-based architecture where agents communicate through well-defined interfaces, enabling loose coupling between components while maintaining tight integration for complex workflows. The scheduler coordinates execution across multiple agents, while the tool executor provides a safe sandbox environment for running external operations.

核心架构

The Agent System consists of five primary components that work together to provide a complete agent execution environment. Each component has distinct responsibilities and interacts with others through well-defined APIs.

graph TD
    A[User Input] --> B[AgentSession]
    B --> C[AgentScheduler]
    C --> D[Scheduler]
    D --> E[ToolExecutor]
    E --> F[External Tools & MCP Servers]
    D --> G[LLM API]
    G --> B
    H[ContextGraph] --> B
    I[ChatRecordingService] --> B

组件职责矩阵

AgentSession (会话管理)

概述

The AgentSession class is the central hub for managing individual agent sessions. It maintains conversation history, handles turn-taking between user and model, and coordinates with various services for persistence and context management. Each session is identified by a unique sessionId that allows for resumption and checkpointing.

The session class implements the getStableId function for generating deterministic identifiers for message turns, using MD5 hashing combined with occurrence tracking to ensure uniqueness even when duplicate messages appear in the conversation history. This is particularly important for maintaining consistent context across session resumption operations.

核心数据结构

interface ConversationRecord {
  sessionId: string;
  projectHash: string;
  startTime: string;
  lastUpdated: string;
  summary?: string;
  memoryScratchpad?: string;
  directories?: string[];
  kind: 'cli' | 'api';
  messages: Message[];
  messageCount: number;
  userMessageCount: number;
  memoryScratchpadIsStale?: boolean;
  firstUserMessage?: string;
  hasUserOrAssistantMessage: boolean;
}

Sources: packages/core/src/services/chatRecordingService.ts:1-50

会话ID生成机制

The session uses a stable ID generation mechanism that creates deterministic identifiers based on message content and role. The algorithm generates an MD5 hash of the turn content and combines it with an occurrence counter to handle duplicate messages:

const turnContent = JSON.stringify(msg.parts);
const h = createHash('md5')
  .update(`${msg.role}:${turnContent}`)
  .digest('hex');
const occurrence = (seenHashes.get(h) || 0) + 1;
seenHashes.set(h, occurrence);
const turnSalt = `${h}_${occurrence}`;

Sources: packages/core/src/context/graph/toGraph.ts:1-30

配置管理

The session integrates with the configuration system to access runtime settings:

getExperimentalDynamicModelConfiguration(): boolean {
  return this.dynamicModelConfiguration;
}

getPendingIncludeDirectories(): string[] {
  return this.pendingIncludeDirectories;
}

clearPendingIncludeDirectories(): void {
  this.pendingIncludeDirectories = [];
}

Sources: packages/core/src/config/config.ts:1-100

AgentScheduler (代理调度)

概述

The AgentScheduler is responsible for coordinating multiple agents within the system. It manages agent registration, task distribution, and result aggregation. When multiple agents are involved in a workflow, the scheduler determines execution order and handles inter-agent communication.

The scheduler supports both sequential and parallel agent execution modes, allowing complex workflows to be composed from simpler agent tasks. It maintains a registry of available agents and their capabilities, enabling dynamic routing of requests to appropriate agents.

内置代理类型

The system includes several built-in agents for common tasks:

CLI Help Agent 实现

The CLI Help Agent is a specialized agent that provides accurate information about Gemini CLI features, configuration, and current state:

const SYSTEM_INSTRUCTION = `You are the **CLI Help Agent**, an expert on Gemini CLI. Your purpose is to provide accurate information about Gemini CLI's features, configuration, and current state.

### Runtime Context
- **CLI Version:** ${cliVersion}
- **Active Model:** ${activeModel}
- **Today's Date:** ${today}

### Instructions
1. **Explore Documentation**: Use the \`get_internal_docs\` tool to find answers.
2. **Be Precise**: Use the provided runtime context and documentation.
3. **Cite Sources**: Include specific documentation files used.
4. **Non-Interactive**: Operate in a loop without user interaction.`;

Sources: packages/core/src/agents/cli-help-agent.ts:1-30

代理注册流程

Agents register with the scheduler using a standard interface that includes system instructions, available tools, and configuration options. The scheduler maintains agent metadata including version, capabilities, and current status.

Scheduler (任务调度)

概述

The Scheduler component is responsible for managing the execution queue of tasks within an agent session. It handles turn orchestration, message processing, and response streaming. The scheduler coordinates between the LLM API and tool execution, ensuring proper sequencing of operations.

The scheduler implements a state machine that tracks the current execution phase and manages transitions between different states such as thinking, tool execution, and response generation.

执行流程

sequenceDiagram
    participant User as User Input
    participant Scheduler
    participant LLM as LLM API
    participant ToolExec as Tool Executor
    participant Session as AgentSession
    
    User->>Scheduler: Send Message
    Scheduler->>Session: Record Message
    Session-->>Scheduler: Acknowledge
    Scheduler->>LLM: Generate Response
    LLM-->>Scheduler: Tool Call Request
    Scheduler->>ToolExec: Execute Tool
    ToolExec-->>Scheduler: Tool Result
    Scheduler->>LLM: Continue Generation
    LLM-->>Scheduler: Final Response
    Scheduler-->>User: Stream Response

工具调用处理

When the LLM generates a tool call, the scheduler intercepts this and delegates to the ToolExecutor. The scheduler manages the execution context, including tool parameters, authentication tokens, and retry logic.

ToolExecutor (工具执行)

概述

The ToolExecutor provides a secure execution environment for tools and external operations. It handles tool discovery, parameter validation, execution, and result formatting. The executor supports multiple tool types including built-in tools, custom skills, and MCP server tools.

工具类型支持

技能执行框架

Skills are executed through a structured framework defined in the SKILL.md specification:

### Bundled Resources (optional)

#### Scripts (`scripts/`)
Executable code for deterministic tasks:
- Token efficient execution
- Deterministic behavior
- LLM-friendly stdout output

#### References (`references/`)
Documentation loaded as needed into context

Sources: packages/core/src/skills/builtin/skill-creator/SKILL.md:1-50

策略引擎集成

The tool executor integrates with the policy engine to enforce security rules. Extensions can contribute policies through TOML configuration files:

# Example policy
[[rules]]
type = "confirmation_required"
command_pattern = "rm -rf.*"

[[rules]]
type = "deny"
command_pattern = "grep.*\\.env"

Sources: packages/cli/src/commands/extensions/examples/policies/README.md:1-30

A2AExecutor (Agent-to-Agent通信)

概述

The A2AExecutor implements the Agent-to-Agent protocol, enabling communication between different agent instances. This is essential for distributed agent systems where multiple agents may run on different processes or machines.

协议消息格式

interface AgentMessage {
  id: string;
  type: 'request' | 'response' | 'event';
  sender: string;
  receiver: string;
  payload: unknown;
  timestamp: number;
}

RPC调度

The executor handles RPC method dispatching and session state management. New RPC methods are registered through the GeminiAgent interface:

// Adding a new RPC method
// 1. Add method to GeminiAgent in acpRpcDispatcher.ts
// 2. Register in AgentSideConnection setup if necessary
// 3. Add serialization logic to acpUtils.ts

Sources: packages/cli/src/acp/README.md:1-50

上下文管理

ContextGraph

The ContextGraph maintains conversation context and generates stable identifiers for message turns. It handles legacy environment header detection and removal:

// Defensive: Skip legacy environment header
if (msg.role === 'user' && msg.parts.length === 1) {
  const text = msg.parts[0].text;
  if (text?.startsWith('<session_context>') && 
      text?.includes('This is the Gemini CLI')) {
    debugLogger.log(
      '[ContextGraphBuilder] Skipping legacy environment header turn.',
    );
    continue;
  }
}

Sources: packages/core/src/context/graph/toGraph.ts:1-30

会话记录服务

The ChatRecordingService handles persistence of conversation history to JSONL format:

export class ChatRecordingService {
  private conversationFile: string | null = null;
  private cachedConversation: ConversationRecord | null = null;
  private sessionId: string;
  // ...
}

Sources: packages/core/src/services/chatRecordingService.ts:50-100

执行模式与策略

审批模式

The system supports multiple approval modes for controlling agent behavior:

isYoloModeDisabled(): boolean {
  return this.disableYoloMode || !this.isTrustedFolder();
}

Sources: packages/core/src/config/config.ts:80-85

策略链解析

The system resolves policy chains based on model configuration:

describe('resolvePolicyChain', () => {
  it('returns a single-model chain for a custom model', () => {
    const chain = resolvePolicyChain(config);
    expect(chain).toHaveLength(1);
    expect(chain[0]?.model).toBe('custom-model');
  });
  
  it('returns the default chain when active model is "auto"', () => {
    const chain = resolvePolicyChain(config);
    expect(chain).toHaveLength(2);
    // Expect default chain [Pro, Flash]
  });
});

Sources: packages/core/src/availability/policyHelpers.test.ts:1-50

扩展机制

MCP服务器集成

The system supports MCP (Model Context Protocol) servers for extending functionality. Configuration is stored in ~/.gemini/settings.json:

{
  "mcpServers": {
    "@github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

自定义技能

Skills are defined through SKILL.md files with YAML frontmatter:

Related Pages

Related topics: Architecture Overview, Session Management

Context and Memory Management

Overview

Context and Memory Management in Gemini CLI is a sophisticated system that enables the CLI to maintain conversational state, optimize token usage, and provide persistent memory across sessions. The system handles conversation history, progressive disclosure of information, and intelligent compression to manage context window constraints.

Architecture Overview

The context management system consists of several interconnected components:

graph TD
    A[User Input] --> B[ContextGraphBuilder]
    B --> C[Turn ID Generation]
    C --> D[Context Manager]
    D --> E[Memory Context Manager]
    E --> F[Chat Recording Service]
    F --> G[Session Persistence]
    D --> H[Chat Compression Service]
    H --> I[Rolling Summary Processor]
    I --> J[Token Optimization]

Core Components

ContextGraphBuilder

The ContextGraphBuilder is responsible for constructing the conversational context from message history. It processes each turn and generates stable identifiers for tracking conversation flow.

Key Responsibilities:

• Iterating through conversation history
• Generating stable turn hashes using MD5
• Creating unique turn IDs with salt-based occurrence tracking
• Skipping legacy environment headers

// Generate a stable salt for this turn based on its role and content
const turnContent = JSON.stringify(msg.parts);
const h = createHash('md5')
  .update(`${msg.role}:${turnContent}`)
  .digest('hex');
const occurrence = (seenHashes.get(h) || 0) + 1;
seenHashes.set(h, occurrence);
const turnSalt = `${h}_${occurrence}`;

Sources: packages/core/src/context/graph/toGraph.ts:31-38

Turn ID Generation

Turn IDs are generated using a combination of message content hashing and a stable ID generation function. This ensures consistent identification across sessions.

Sources: packages/core/src/context/graph/toGraph.ts:39

Legacy Header Handling

The system includes defensive logic to skip legacy environment headers that contain <session_context> markers. This prevents duplicate or stale context from being reintroduced.

if (msg.role === 'user' && msg.parts.length === 1) {
  const text = msg.parts[0].text;
  if (
    text?.startsWith('<session_context>') &&
    text?.includes('This is the Gemini CLI')
  ) {
    debugLogger.log(
      '[ContextGraphBuilder] Skipping legacy environment header turn from graph.',
    );
    continue;
  }
}

Sources: packages/core/src/context/graph/toGraph.ts:19-29

Chat Recording Service

The ChatRecordingService manages persistent storage of conversation history and session metadata.

ConversationRecord Model

Sources: packages/core/src/services/chatRecordingService.ts:1-30

Session State Tracking

The service tracks whether sessions contain user or assistant messages:

hasUserOrAssistantMessage:
  options?.metadataOnly && metadataMessages.length > 0
    ? metadataMessages.some(
        (m) => m.type === 'user' || m.type === 'gemini',
      )
    : hasUserOrAssistant,

Sources: packages/core/src/services/chatRecordingService.ts:57-62

Progressive Disclosure Design

Gemini CLI implements a three-level loading system to manage context efficiently:

graph LR
    A[Metadata<br/>name + description] --> B[SKILL.md Body<br/>Instructions]
    B --> C[Bundled Resources<br/>Scripts/References]

Loading Levels

Sources: packages/core/src/skills/builtin/skill-creator/SKILL.md

Bundled Resources Organization

scripts/       - Executable code (Node.js/Python/Bash)
references/    - Documentation loaded into context
assets/        - Files used in output (templates, icons)

Memory Scratchpad

The system supports a memory scratchpad feature that persists across sessions:

• Staleness Tracking: The system can flag when the scratchpad content becomes stale
• Fallback Detection: Falls back to first user message if no user message found

memoryScratchpadIsStale: isTrackingMemoryScratchpadFreshness
  ? memoryScratchpadIsStale
  : undefined,
firstUserMessage: fallbackFirstUserMessage,

Sources: packages/core/src/services/chatRecordingService.ts:52-55

Folder Trust and Configuration Discovery

When a folder is trusted, Gemini CLI loads its local configurations including:

• Custom commands
• Hooks
• MCP servers
• Agent skills
• Settings

<Box>
  Trusting a folder allows Gemini CLI to load its local configurations,
  including custom commands, hooks, MCP servers, agent skills, and
  settings. These configurations could execute code on your behalf or
  change the behavior of the CLI.
</Box>

Sources: packages/cli/src/ui/components/FolderTrustDialog.tsx

Discovery Results

The system performs security validation on discovered configurations:

CLI Help Agent Memory

The CLI Help Agent provides contextual assistance with runtime awareness:

### Runtime Context
- **CLI Version:** ${cliVersion}
- **Active Model:** ${activeModel}
- **Today's Date:** ${today}

Sources: packages/core/src/agents/cli-help-agent.ts

Agent Instructions

1. Explore Documentation: Use the get_internal_docs tool to find answers
2. Be Precise: Use provided runtime context and documentation
3. Cite Sources: Include specific documentation files used
4. Non-Interactive: Operate autonomously without user queries

SDK Integration

The Gemini CLI SDK provides programmatic access to the context system:

import { GeminiCliAgent } from '@google/gemini-cli-sdk';

const agent = new GeminiCliAgent({
  instructions: 'You are a helpful assistant.',
});

const stream = agent.sendStream('query', signal);

Sources: packages/sdk/README.md

Data Flow Summary

graph TD
    subgraph "Input Processing"
        A[User Input] --> B[ContextGraphBuilder]
        B --> C[Turn Hash Generation]
        C --> D[Stable ID Creation]
    end
    
    subgraph "Memory Management"
        D --> E[Memory Context Manager]
        E --> F[Session Metadata]
        F --> G[Persistent Storage]
    end
    
    subgraph "Optimization"
        D --> H[Compression Service]
        H --> I[Rolling Summary]
        I --> J[Token Budget]
    end
    
    subgraph "Retrieval"
        G --> K[Chat Recording Service]
        K --> L[Conversation Record]
        L --> M[Context Window]
    end

Configuration Options

Security Considerations

The context management system includes several security measures:

1. Folder Trust: User confirmation required before loading folder configurations
2. Policy Engine: Security rules can be contributed via extensions
3. Path Validation: Safety checkers validate file paths for write operations
4. Discovery Errors: Configuration parsing failures are surfaced to users

Sources: packages/cli/src/commands/extensions/examples/policies/README.md

Summary

The Context and Memory Management system in Gemini CLI provides:

• Stable Turn Identification: MD5-based hashing with occurrence tracking
• Session Persistence: Full conversation history with metadata
• Progressive Disclosure: Three-level loading for token optimization
• Security: Folder trust validation and policy enforcement
• SDK Access: Programmatic interface for external agents

Related Pages

Related topics: Agent System, Sandboxing and Security

Tools Reference

Overview

The Tools system in Gemini CLI provides the foundational capabilities that enable the AI assistant to interact with filesystems, execute commands, search codebases, and connect to external services through MCP (Model Context Protocol) servers. Tools serve as the primary interface between the LLM and the operating environment, allowing the model to read, write, and manipulate files and execute system operations.

Tools are registered dynamically based on configuration and model capabilities, with model-specific optimizations for tool descriptions and schemas. The system supports both built-in core tools and extensible MCP tool integrations.

Sources: packages/core/src/tools/definitions/coreTools.ts:1-50

Architecture Overview

graph TD
    A[User Request] --> B[GeminiAgent]
    B --> C[Tool Registry]
    C --> D[Core Tools]
    C --> E[MCP Tools]
    D --> F[read_file]
    D --> G[write_file]
    D --> H[shell/grep/glob]
    D --> I[web_search]
    E --> J[MCP Server 1]
    E --> K[MCP Server 2]
    F --> L[Filesystem]
    G --> L
    H --> M[System Commands]
    I --> N[Google Search API]
    J --> O[External Services]

Tool Registration System

Tools are registered through a centralized ToolRegistry that manages availability based on configuration and platform capabilities. The registration follows a conditional pattern where tools are only registered if explicitly enabled or if no restrictions exist.

Sources: packages/core/src/config/config.ts:150-180

Dynamic Tool Registration

graph TD
    A[Configuration Load] --> B{coreTools defined?}
    B -->|Yes| C{Check tool in list}
    B -->|No| D[Enable all by default]
    C -->|Match found| E[Register Tool]
    C -->|No match| F[Skip Tool]
    D --> E
    E --> G[Tool available to Agent]

The maybeRegister function controls tool availability:

Sources: packages/core/src/config/config.ts:130-150

Core Tools

Core tools are built-in capabilities that provide filesystem access, search functionality, and command execution. These tools are optimized per model family.

Tool Categories

Sources: packages/core/src/tools/definitions/coreTools.ts:40-80

File Operations

Read File Tool

The read_file tool provides controlled access to file contents with optional line range selection.

Parameters:

Behavior:

• Returns file contents as a string
• Supports partial file reads via line range
• Validates file path exists before reading
• Respects .gemini-ignore patterns when configured

Sources: packages/core/src/tools/read-file.ts:1-60

Write File Tool

The write_file tool creates or overwrites files with specified content.

Parameters:

Behavior:

• Creates parent directories if they don't exist
• Overwrites existing files silently
• Returns confirmation message on success
• Subject to security policy checks

Sources: packages/core/src/tools/write-file.ts:1-50

Edit/Replace Tool

The replace tool performs targeted modifications to existing files using diff/patch format.

Parameters:

Patch Format:

--- /absolute/path/to/file
+++ /absolute/path/to/file
@@ -start,count +start,count @@
 context line
 -removed line
 +added line

Sources: packages/core/src/agents/skill-extraction-agent.ts:50-80

Search Tools

Grep Tool

The grep_search tool performs text pattern matching across files with extensive filtering options.

Parameters:

Sources: packages/core/src/tools/grep.ts:1-80

Ripgrep Tool

When available, ripgrep provides faster searching with the same interface as the standard Grep tool. The system automatically falls back to the standard implementation if Ripgrep is not installed.

Sources: packages/core/src/config/config.ts:160-175

Glob Tool

The glob tool finds files matching shell-style wildcard patterns.

Parameters:

Sources: packages/core/src/tools/glob.ts:1-50

Directory Navigation

List Directory Tool

The list_directory tool provides directory contents with optional filtering.

Parameters:

Features:

• Returns file and directory names
• Supports ignore patterns for filtering
• Respects gitignore when configured

Sources: packages/core/src/tools/list-directory.ts:1-50

Shell Command Execution

Run Shell Command Tool

The run_shell_command tool executes system commands in a sandboxed environment.

Parameters:

Security Features:

• Subject to policy engine rules
• May require user confirmation for destructive commands
• Path safety validation for file operations
• Timeout protection against hanging processes

Sources: packages/core/src/tools/shell.ts:1-100

graph TD
    A[Command Request] --> B{Policy Check}
    B -->|Allowed| C[Environment Setup]
    B -->|Denied| D[User Confirmation]
    B -->|Blocked| E[Error Response]
    D -->|Approved| C
    D -->|Denied| E
    C --> F[Spawn Process]
    F --> G{Timeout?}
    G -->|Yes| H[Terminate]
    G -->|No| I[Capture Output]
    I --> J[Return Result]
    H --> K[Timeout Error]

Web Tools

Google Web Search

The google_web_search tool provides real-time internet search capabilities grounded in Google Search.

Parameters:

Behavior:

• Returns search results with snippets
• May be disabled via configuration
• Subject to rate limiting

Sources: packages/core/src/tools/web-search.ts:1-50

Web Fetch

The web_fetch tool retrieves content from URLs.

Parameters:

MCP Tool Integration

MCP (Model Context Protocol) tools allow integration with external MCP servers, extending Gemini CLI's capabilities.

Architecture

graph TD
    A[Gemini CLI] --> B[MCP Tool Bridge]
    B --> C[MCP Server 1]
    B --> D[MCP Server 2]
    B --> E[MCP Server N]
    C --> F[External Service]
    D --> G[Database]
    E --> H[Custom Tools]
    B --> I[Resource Reader]
    B --> J[Resource Lister]

MCP Tool Types

Sources: packages/core/src/tools/mcp-tool.ts:1-100

Configuration

MCP servers are configured in ~/.gemini/settings.json:

{
  "mcpServers": {
    "@github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  }
}

Model-Specific Tool Manifests

Different model families may have optimized tool definitions with adjusted descriptions and parameter schemas.

Gemini 3 Tool Manifest

The Gemini 3 family uses optimized tool definitions that may include:

• Streamlined descriptions for reduced token usage
• Adjusted parameter names for consistency
• Model-specific capability hints

Sources: packages/core/src/tools/definitions/gemini-3.ts:1-50

Tool Definition Snapshot Testing

Tool definitions are validated against snapshots to ensure consistency:

const modelIds = ['gemini-2.5-pro', 'gemini-3-pro-preview'];
const tools = [
  { name: 'read_file', definition: READ_FILE_DEFINITION },
  { name: 'write_file', definition: WRITE_FILE_DEFINITION },
  { name: 'grep_search', definition: GREP_DEFINITION },
  // ... more tools
];

Sources: packages/core/src/tools/definitions/coreToolsModelSnapshots.test.ts:30-60

Tool Response Format

All tools return responses in a standardized format:

interface ToolResult {
  tool_call_id: string;
  result: {
    success: boolean;
    data?: string | object;
    error?: string;
  };
}

Security and Policy Engine

Tools are subject to security policies defined by the Policy Engine extension system.

Policy Types

Sources: packages/cli/src/commands/extensions/examples/policies/README.md:1-30

Folder Trust and Tool Access

When a folder is trusted, its local configurations can modify tool behavior:

• Custom commands
• MCP server configurations
• Agent skills
• Extension policies

Untrusted folders restrict tool access to prevent potentially harmful operations.

Sources: packages/cli/src/ui/components/FolderTrustDialog.tsx:20-40

Tool Availability Matrix

Extension Points

Custom Tools via MCP

External tools can be integrated through MCP servers:

> @github List my open pull requests
> @slack Send a summary to #dev channel
> @database Find inactive users

Custom Commands

Custom slash commands can be defined in project directories and provide task-specific tool combinations.

Best Practices

1. Use Line Ranges: When reading large files, specify line ranges to reduce token usage
2. Respect Ignores: Let tools respect .gitignore and .gemini-ignore patterns
3. Timeout Configuration: Set appropriate timeouts for shell commands
4. MCP Security: Only enable trusted MCP servers
5. Path Validation: Use absolute paths to avoid ambiguity

Related Documentation

• Configuration Guide
• MCP Server Integration
• Policy Engine
• Keyboard Shortcuts

Related Pages

Related topics: Tools Reference, Skills and Extensions

MCP Integration

Model Context Protocol (MCP) Integration enables Gemini CLI to connect with external MCP servers, extending the CLI's capabilities with custom tools, prompts, and resources. This integration follows the MCP specification, allowing seamless communication between Gemini CLI and any compliant MCP server implementation.

Overview

MCP Integration serves as a bridge between Gemini CLI and external tools. When configured, MCP servers can expose:

• Tools: Executable functions that the AI can call (e.g., fetch_posts, database queries, GitHub operations)
• Prompts: Pre-defined prompt templates for specific use cases
• Resources: Static data that can be loaded into context as needed

The integration supports both sandboxed and non-sandboxed execution modes, with appropriate security measures including consent prompts and path restrictions.

Architecture

The MCP Integration system comprises several core components that work together to manage server lifecycle, tool exposure, and prompt loading.

graph TD
    A[Gemini CLI] --> B[McpClientManager]
    B --> C[McpClient instances]
    C --> D[MCP Servers]
    E[McpPromptLoader] --> F[Prompts Registry]
    G[McpToolWrapper] --> H[Tool Definitions]
    D --> I[JSON-RPC Transport]
    I --> C
    H --> A

Core Components

MCP Client Manager

The McpClientManager is the central orchestrator for all MCP server connections. It handles:

• Server initialization and configuration loading
• Connection lifecycle management
• Tool registration and updates
• Cleanup and graceful shutdown

Server Discovery

MCP servers can be configured in two ways:

1. Global Configuration: Defined in ~/.gemini/settings.json
2. Per-Project Configuration: Defined in ~/.gemini/settings.json for the active workspace

graph TD
    A[Load Settings] --> B[Get mcpServers config]
    B --> C{Server enabled?}
    C -->|Yes| D[Check enablement]
    C -->|No| E[Skip]
    D --> F[canLoadServer check]
    F --> G{Allowed?}
    G -->|Yes| H[Create MCP Client]
    G -->|No| I[Block with message]
    H --> J[Connect via Transport]
    J --> K[Register tools]

Sources: packages/cli/src/commands/mcp/list.ts:1-50

Configuration Schema

MCP server configuration follows this structure:

interface MCPServerConfig {
  command: string;           // Executable to run (e.g., 'npx', 'node')
  args?: string[];           // Command arguments
  env?: Record<string, string>;  // Environment variables
  disabled?: boolean;       // Enable/disable server
}

Configuration is merged from multiple sources with appropriate precedence rules applied by the settings system.

Sources: packages/cli/src/commands/mcp/list.ts:30-40

MCP Client

The McpClient handles the actual communication with an MCP server using the JSON-RPC protocol over stdio transport. Each client instance maintains:

• A transport connection to the server
• Registered tool definitions
• Server capabilities and metadata

Tool Registration Flow

sequenceDiagram
    participant CLI as Gemini CLI
    participant Manager as McpClientManager
    participant Client as McpClient
    participant Server as MCP Server
    participant Browser as Browser Manager

    CLI->>Manager: Initialize servers
    Manager->>Client: Create client instance
    Client->>Server: Initialize connection
    Server-->>Client: Server capabilities
    Client->>Server: List tools request
    Server-->>Client: Tool definitions
    Client->>Manager: Register tools
    Manager->>Browser: Convert to FunctionDeclaration
    Browser->>CLI: Expose tools to model

Sources: packages/core/src/agents/browser/mcpToolWrapper.ts:1-50

Tool Wrapper

The McpToolWrapper transforms MCP tool definitions into Gemini-compatible function declarations. This conversion ensures that:

1. Tool schemas are compatible with Gemini's function calling format
2. Descriptions are augmented with usage hints
3. Input schemas are properly formatted as JSON Schema

Schema Conversion

function convertMcpToolToFunctionDeclaration(mcpTool: McpTool): FunctionDeclaration {
  return {
    name: mcpTool.name,
    description: mcpTool.description ?? '',
    parametersJsonSchema: mcpTool.inputSchema ?? {
      type: 'object',
      properties: {},
    },
  };
}

Sources: packages/core/src/agents/browser/mcpToolWrapper.ts:60-75

Description Augmentation

The wrapper augments MCP tool descriptions with semantic hints that help the model make correct tool choices:

const augmentedDescription = augmentToolDescription(
  mcpTool.name,
  mcpTool.description ?? '',
);

This approach reduces system prompt overhead by embedding usage rules directly in tool descriptions.

Sources: packages/core/src/agents/browser/mcpToolWrapper.ts:45-50

Prompt Loading

The McpPromptLoader handles loading and registering MCP prompt templates. Prompts are discovered from connected MCP servers and made available for use in conversations.

Prompt Structure

MCP prompts can include:

• Name: Unique identifier for the prompt
• Description: Human-readable explanation of when to use the prompt
• Arguments: Template variables that can be customized at runtime
• Template: The actual prompt content with variable placeholders

Sources: packages/cli/src/services/McpPromptLoader.ts

MCP Server Implementation

Gemini CLI provides example MCP server implementations demonstrating how to create compliant servers.

Basic Example

The basic MCP server example (packages/cli/src/commands/extensions/examples/mcp-server) exposes:

• Tool: fetch_posts - Mock-fetches posts
• Prompt: poem-writer - Generates poems

Extension Structure

mcp-server/
├── example.js          # Server entry point
├── gemini-extension.json  # Configuration manifest
└── package.json        # Dependencies

Server Entry Point

Servers implement the MCP specification using @modelcontextprotocol/sdk:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

const server = new Server(
  { name: 'example-mcp-server', version: '1.0.0' },
  { capabilities: { tools: {}, prompts: {} } }
);

Sources: packages/cli/src/commands/extensions/examples/mcp-server/README.md

Security Model

MCP Integration includes multiple security layers:

Consent and Allowlists

Sources: packages/cli/src/commands/mcp/list.ts:20-25

Policy Engine Integration

The policy engine example extension demonstrates how to add security rules:

• Confirmation Rules: Require user confirmation for dangerous operations (e.g., rm -rf)
• Denial Rules: Block access to sensitive resources (e.g., searching for .env files)
• Safety Checkers: Validate operations before execution (e.g., path validation)

Security note: Extensions can strengthen security but cannot bypass user confirmation or enable yolo mode.

Sources: packages/cli/src/commands/extensions/examples/policies/README.md

Usage Examples

Configure MCP Server

Add server configuration to ~/.gemini/settings.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
    }
  }
}

Using MCP Tools

After configuration, tools are automatically available:

> @github List my open pull requests
> @database Run a query to find inactive users

Creating Custom Server

1. Create server directory structure
2. Implement MCP server using @modelcontextprotocol/sdk
3. Add gemini-extension.json manifest
4. Link extension: gemini extensions link <path>

Command Reference

List MCP Servers

gemini mcp list

Displays all configured MCP servers with their status.

Sources: packages/cli/src/commands/mcp/list.ts

MCP Server Integration Guide

For detailed setup instructions, see the MCP Server Integration guide.

See Also

• Custom Commands
• Policy Engine
• Extension Development
• Official MCP Documentation

Related Pages

Related topics: MCP Integration

Skills and Extensions

Overview

Skills and Extensions are the two primary extensibility mechanisms in Gemini CLI. Skills enable the CLI to handle specialized, domain-specific tasks with structured guidance, while Extensions provide a comprehensive framework for contributing custom tools, policies, and integrations.

Skills are markdown-based packages that provide instructions and reusable resources for handling specific task types. They are loaded into context when triggered and contain documentation, scripts, and assets.

Extensions are npm-based packages that extend Gemini CLI's capabilities through custom commands, MCP server configurations, policy rules, and hooks. They provide a richer, more programmatic extensibility model.

Related Pages

Related topics: Policy Engine, Tools Reference

Sandboxing and Security

Overview

Gemini CLI implements a multi-layered security architecture that protects users through sandboxed execution environments, path validation, trusted folder mechanisms, and an extensible policy engine. The system is designed to execute AI-generated code and commands safely while giving users fine-grained control over security boundaries.

Architecture

The sandboxing system uses platform-specific implementations to handle execution isolation across different operating systems. The configuration system acts as the central authority for path validation and access control.

graph TD
    A[User Request] --> B[Config System]
    B --> C{Path Validation}
    C -->|Allowed| D[Sandbox Manager]
    C -->|Denied| E[Access Rejected]
    D --> F{Linux Sandbox}
    D --> G{macOS Sandbox}
    D --> H{Windows Sandbox}
    F --> I[Docker Container]
    G --> J[Apple Silicon / Sandbox Profile]
    H --> K[Windows Sandbox]
    I --> L[Tool Execution]
    J --> L
    K --> L

Sandbox Manager Architecture

The sandbox system is orchestrated through a centralized SandboxManager service that delegates to platform-specific implementations.

Platform-Specific Implementations

Sandbox Image Configuration

Sandbox environments use pre-built Docker images defined in the root package.json:

{
  "config": {
    "sandboxImageUri": "us-docker.pkg.dev/gemini-code-dev/gemini-cli/sandbox:0.44.0-nightly.20260512.g022e8baef"
  }
}

Sources: package.json:11

Path Validation System

The path validation system prevents the agent from accessing files outside authorized boundaries. This is implemented in the Config class through two primary methods.

Access Control Logic

isPathAllowed(absolutePath: string): boolean {
  const resolvedPath = resolveToRealPath(absolutePath);
  // Check inbox isolation first
  // Check workspace boundaries
  // Check project temp directory
}

validatePathAccess(absolutePath: string): string | null {
  if (this.isPathAllowed(absolutePath)) {
    return null;
  }
  return `Path not in workspace: Attempted path "${absolutePath}" resolves outside the allowed workspace directories`;
}

Sources: packages/core/src/config/config.ts Sources: packages/core/src/tools/confirmation-policy.test.ts

Allowed Path Categories

Inbox Isolation

The .inbox/ directory within the project memory temp directory receives special treatment. The main agent is denied write access to prevent bypassing the memory extraction review flow:

graph LR
    A[Main Agent] -->|DENIED| B[.inbox/ directory]
    C[Extraction Agent] -->|WRITE ALLOWED| B
    D[Review Flow] -->|READ| B

Sources: packages/core/src/config/config.ts

Trusted Folders System

The trusted folders mechanism allows users to authorize specific directories for configuration loading while maintaining security boundaries.

What Trust Enables

When a folder is trusted, Gemini CLI loads:

• Custom commands
• Hooks
• MCP server configurations
• Agent skills
• Local settings

Security Dialog

When discovering a new folder, users are presented with the FolderTrustDialog component that displays:

// Security warnings and errors are displayed to the user
{hasWarnings && (
  <Box>
    <Text color={theme.status.warning}>⚠️ Security Warnings:</Text>
    {discoveryResults.securityWarnings.map((warning, i) => (
      <Text key={i} color={theme.status.warning}>
        • {stripAnsi(warning)}
      </Text>
    ))}
  </Box>
)}

Sources: packages/cli/src/ui/components/FolderTrustDialog.tsx

Discovery Results

The folder discovery process returns categorized items:

Policy Engine

Extensions can contribute security rules and safety checkers through the policy engine. This allows the community to extend built-in security without modifying core code.

Rule Types

Extension Policy Structure

extension/
├── gemini-extension.json
└── policies/
    ├── confirmation-rules.toml
    ├── denial-rules.toml
    └── safety-checkers.toml

Sources: packages/cli/src/commands/extensions/examples/policies/README.md

Security Enforcement

Critical: Gemini CLI ignores allow decisions and yolo mode configurations contributed by extensions. This ensures that:

• Extensions can strengthen security
• Extensions cannot bypass user confirmation
• Malicious extensions cannot weaken protections

Sources: packages/cli/src/commands/extensions/examples/policies/README.md

Configuration Reference

Settings File Location

User settings are stored at ~/.gemini/settings.json

Key Security Settings

Workspace Context

interface WorkspaceContext {
  isPathWithinWorkspace(path: string): boolean;
  getDirectories(): string[];
}

The workspace context is queried during path validation to determine if a requested file operation falls within authorized boundaries.

Security Best Practices

For Users

1. Review folder trust requests - Only trust folders containing code you control
2. Understand policy rules - Read denial messages to understand why operations are blocked
3. Use workspace isolation - Keep sensitive files outside workspace directories

For Extension Developers

1. Contribute restrictive rules - Extensions should only add protections, never remove them
2. Follow policy TOML format - Use structured definitions for predictable behavior
3. Test edge cases - Validate paths resolve correctly across platforms

Summary

Gemini CLI's security architecture combines:

• Platform-specific sandboxing for code execution isolation
• Path validation for filesystem access control
• Trusted folder system for configuration security
• Policy engine for extensible rule definitions
• Inbox isolation for memory extraction workflow integrity

This multi-layered approach allows the CLI to safely execute AI-generated code while giving users transparency and control over security boundaries.

Related Pages

Related topics: Sandboxing and Security, Agent System

Policy Engine

Overview

The Policy Engine is a security infrastructure component within Gemini CLI that enforces security rules and safety checks for file operations and command execution. It provides a declarative mechanism for defining policies through TOML configuration files, enabling administrators and extensions to contribute security rules without modifying core application code.

The Policy Engine operates as a late-stage validation layer, intercepting operations after the AI model has decided to execute them but before the operations are actually performed. This architecture allows for granular control over potentially dangerous operations while maintaining flexibility for extension contributions.

Architecture

Core Components

The Policy Engine consists of three primary layers:

Evaluation Flow

graph TD
    A[Operation Request] --> B{Policy Engine}
    B --> C[Load Policies from TOML]
    C --> D[Apply Security Rules]
    D --> E{Rule Match?}
    E -->|Yes| F[Prompt User Confirmation]
    E -->|No| G[Apply Safety Checkers]
    F --> H{User Approves?}
    H -->|Yes| G
    H -->|No| I[Block Operation]
    G --> J{Safety Valid?}
    J -->|Yes| K[Execute Operation]
    J -->|No| I
    I --> L[Return Error/Deny Message]
    K --> M[Operation Complete]

Policy Configuration

Configuration File Location

Policy files are stored in a policies/ directory within extension packages. Each policy is defined as a separate .toml file containing rule definitions and safety checker configurations.

Policy Types

The Policy Engine supports two categories of policies:

#### Security Rules

Security rules define conditional logic that triggers user confirmation or denies operations based on specific patterns. Rules are evaluated before operation execution and can:

• Require user confirmation for dangerous commands
• Deny operations matching specific patterns
• Provide custom deny messages explaining why an operation was blocked

#### Safety Checkers

Safety checkers perform validation on operation parameters such as file paths. Unlike rules that evaluate operation context, safety checkers focus on structural validation of operation inputs.

Extension Integration

Registering Policy Extensions

Extensions can contribute policies by including a policies/ directory with TOML files. The extension manifest (gemini-extension.json) identifies it as a policy contributor.

Security Constraints

For security, Gemini CLI enforces strict constraints on extension-contributed policies:

[security]
# Gemini CLI ignores these configurations from extensions
allow_decisions = false  # Ignored
yolo_mode = false        # Ignored

This design ensures that extensions can only strengthen security by adding more restrictive rules—they cannot weaken security by bypassing user confirmation.

Built-in Policies

rm -rf Rule Example

The following demonstrates a policy that requires confirmation for recursive directory deletion:

[[rules]]
id = "prevent-recursive-delete"
description = "Require confirmation for rm -rf commands"

[rules.condition]
command_pattern = "rm.*-rf.*"

[rules.action]
type = "confirm"
message = "This will recursively delete directories. Are you sure?"

Sources: packages/cli/src/commands/extensions/examples/policies/README.md:1-30

Secret File Access Rule Example

Policies can prevent searching for sensitive files:

[[rules]]
id = "prevent-secret-search"
description = "Deny grep searches for sensitive files"

[rules.condition]
command_pattern = "grep.*\\.env"

[rules.action]
type = "deny"
message = "Searching for .env files is not allowed for security reasons"

Sources: packages/cli/src/commands/extensions/examples/policies/README.md:1-30

File Path Safety Checker Example

Safety checkers validate operation parameters:

[[safety_checkers]]
id = "allowed-path"
description = "Validate file paths for write operations"

[safety_checkers.validator]
type = "path_validation"
allowed_paths = ["/home/user/project", "/tmp/uploads"]

Policy Chain Resolution

The Policy Engine supports model-specific policy chains, allowing different security rules based on the active AI model. The resolvePolicyChain function determines which policies apply for a given model configuration.

graph LR
    A[Model Config] --> B{Is Custom Model?}
    B -->|Yes| C[Single-Model Chain]
    B -->|No| D{Is in Catalog?}
    D -->|Yes| E[Use Catalog Order]
    D -->|No| F[Default Chain: Pro → Flash]

Sources: packages/core/src/availability/policyHelpers.test.ts:1-50

Folder Trust Integration

The Policy Engine integrates with Gemini CLI's folder trust system. Policies are only loaded from trusted folders to prevent malicious configuration injection.

The isYoloModeDisabled method checks both the global YOLO disable flag and the folder trust status:

isYoloModeDisabled(): boolean {
  return this.disableYoloMode || !this.isTrustedFolder();
}

Sources: packages/core/src/config/config.ts:200-203

Security Warnings and Errors

When loading policies from a folder, the system reports:

• Discovery Errors: Problems parsing or loading policy files
• Security Warnings: Potentially risky configurations detected
• Loaded Items: Policies successfully loaded and active

interface DiscoveryResults {
  discoveryErrors: string[];
  securityWarnings: string[];
  loadedPolicies: Policy[];
}

Sources: packages/cli/src/ui/components/FolderTrustDialog.tsx:1-60

Configuration Options

Core Policy Settings

Policy File Loading

Best Practices

Writing Secure Policies

1. Use specific patterns: Avoid overly broad patterns that could match legitimate operations
2. Provide clear messages: Explain why an operation requires confirmation
3. Validate file paths: Use safety checkers for path-based operations
4. Test edge cases: Ensure policies don't block necessary operations

Policy Testing

To test policies contributed by extensions:

# Link the extension
gemini extensions link packages/cli/src/commands/extensions/examples/policies

# Restart Gemini CLI session
# Policies will be loaded from the linked extension

Debugging Policy Evaluation

When policies don't behave as expected:

1. Verify the extension is properly linked
2. Check the folder is marked as trusted
3. Review TOML syntax for parsing errors
4. Confirm rule patterns match the actual command strings

Summary

The Policy Engine provides a robust, extensible security framework for Gemini CLI. By supporting declarative TOML-based policy definitions, extensions can contribute security rules without modifying core code. The enforced security constraints ensure that extensions can only strengthen security—never weaken it—making the system resistant to potentially malicious extension configurations.

Related Pages

Related topics: Session Management

Terminal UI Components

Overview

The Terminal UI Components system provides a rich, interactive command-line interface for Gemini CLI. Built on Ink (React for CLIs), the UI framework delivers a modern, terminal-native experience with support for themes, dialogs, user authentication, and real-time updates.

The component architecture follows a modular design pattern, separating concerns between layout containers, interactive dialogs, informational displays, and message rendering components.

Architecture

graph TD
    subgraph "UI Layer"
        A[App.tsx] --> B[AppHeader]
        A --> C[MainContent]
        A --> D[Composer]
    end
    
    subgraph "Dialogs"
        E[AuthDialog] --> F[RadioButtonSelect]
        G[ModelDialog] --> H[ModelQuotaDisplay]
        I[FolderTrustDialog] --> J[DiscoveryResults]
        K[InboxDialog] --> L[ScrollableDiffViewport]
    end
    
    subgraph "Messages"
        M[GeminiMessage] --> N[StreamingState]
        O[ToolConfirmationMessage] --> P[ConfirmationDetails]
    end
    
    subgraph "Theming"
        Q[ThemeManager] --> R[Theme Types]
        Q --> S[Custom Extensions]
    end

Component Categories

1. Layout Components

#### AppHeader The main header component displaying CLI branding, version information, and user identity.

Key Features:

• Dynamic layout: switches between row and column orientation based on terminal width
• Update notifications with spinner animation during version checks
• User identity display (email and plan information)
• Collapsible tips section
• Configurable branding via logo text art

Source: packages/cli/src/ui/components/AppHeader.tsx:1-100

#### Composer Input component for user commands and messages.

Provides the text input interface for interacting with Gemini CLI, supporting multi-line input and command submission.

2. Dialog Components

#### AuthDialog Handles user authentication flow with multiple provider options.

graph LR
    A[Launch] --> B{Auth Method?}
    B -->|OAuth| C[Google Login]
    B -->|Token| D[API Key Input]
    B -->|Skip| E[Continue Anonymously]
    C --> F[Restart CLI]
    D --> G[Validate Token]
    E --> H[Limited Mode]

Features:

• Radio button selection for authentication methods
• Error state handling with visual feedback
• Links to Terms of Service and Privacy Notice
• OAuth flow with automatic CLI restart

Source: packages/cli/src/ui/auth/AuthDialog.tsx:1-80

#### ModelDialog Displays available models with quota information and allows model selection.

Source: packages/cli/src/ui/components/ModelDialog.tsx:1-60

#### FolderTrustDialog Security-focused dialog for approving folder configurations.

Key Sections:

1. Trust Explanation - Documents what configurations will be loaded
2. Discovery Results - Shows found extensions, commands, hooks, and skills
3. Security Warnings - Highlights potentially risky configurations
4. Discovery Errors - Reports parsing or loading failures

Source: packages/cli/src/ui/components/FolderTrustDialog.tsx:1-100

#### InboxDialog Displays notification patches and skill updates available for installation.

Source: packages/cli/src/ui/components/InboxDialog.tsx:1-120

3. Message Components

#### GeminiMessage Renders AI-generated responses with markdown support.

Rendering Modes:

• Markdown Rendered (default): Full markdown parsing with syntax highlighting
• Raw Markdown: Syntax highlighting without line numbers

Configuration Options:

interface GeminiMessageProps {
  text: string;           // Message content
  isPending: boolean;     // Streaming indicator
  terminalWidth: number;  // Layout adaptation
  renderMarkdown?: boolean;
  streamingState?: StreamingState;
}

Source: packages/cli/src/ui/components/messages/GeminiMessage.test.tsx:1-50

#### ToolConfirmationMessage Displays interactive confirmation prompts for tool execution.

Supported Types:

• edit - File modification operations
• read - Content retrieval requests
• execute - Command execution confirmations
• delete - Resource removal confirmations

States:

• Normal confirmation view
• In-progress indicator ("Save and close external editor")
• Security warning display
• System message overlay

Source: packages/cli/src/ui/components/ToolConfirmationMessage.tsx:1-100

4. Information Components

#### AboutBox Displays system and version information.

Source: packages/cli/src/ui/components/AboutBox.tsx:1-60

Theming System

The UI supports customizable color themes that apply consistent styling across all components.

Theme Structure

interface Theme {
  text: {
    primary: string;
    secondary: string;
    accent: string;
    link: string;
  };
  status: {
    success: string;
    warning: string;
    error: string;
  };
  border: {
    default: string;
  };
  ui: {
    focus: string;
  };
}

Theme Configuration

Users can create custom themes by:

``json { "ui": { "theme": "theme-name (extension-name)" } } ``

1. Creating an extension with theme definition in gemini-extension.json
2. Setting the theme in ~/.gemini/settings.json:

Available UI Settings

Component Composition Patterns

Dialog Pattern

All dialogs follow a consistent structure:

<Box borderStyle="round" borderColor={theme.ui.focus}>
  <Box flexDirection="column">
    {/* Title */}
    <Text bold>{title}</Text>
    
    {/* Content */}
    {children}
    
    {/* Footer */}
    <DialogFooter 
      primaryAction="Enter to select"
      cancelAction="Esc to close"
    />
  </Box>
</Box>

Responsive Layout

Components adapt to terminal width using:

• Flexbox with flexDirection switching (row/column)
• Percentage-based widths (width="35%")
• Conditional rendering based on terminalWidth
• Maximum size constraints via MaxSizedBox

Color Application

Components use semantic color tokens:

• theme.text.primary - Main content text
• theme.text.secondary - Supporting text
• theme.text.accent - Highlighted elements
• theme.text.link - Interactive links
• theme.status.* - State indicators (success, warning, error)

State Management

UI State Context

Components access shared state through React context:

interface UIState {
  renderMarkdown: boolean;
  streamingState: StreamingState;
  terminalWidth: number;
}

Component Communication

Security Features

Folder Trust System

The FolderTrustDialog implements security boundaries:

1. Discovery Phase: Scans for configuration files
2. Warning Phase: Identifies potentially dangerous configurations
3. Approval Phase: User explicitly approves folder access
4. Execution Phase: Loads approved configurations

Data Collection Opt-In

Users can control whether usage data is collected:

• UI toggle in privacy settings
• Persisted preference in settings.json
• Clear documentation in privacy notices

Testing Approach

Components use snapshot testing with renderWithProviders:

it('renders pending state', async () => {
  const { lastFrame } = await renderWithProviders(
    <GeminiMessage {...props} isPending={true} />,
    { uiState: { renderMarkdown: true } }
  );
  expect(lastFrame()).toMatchSnapshot();
});

Test utilities provide:

• Mocked Ink components
• Theme injection
• State context setup
• Terminal width simulation

Best Practices

Component Guidelines

1. Accessibility: Support keyboard navigation (Enter, Escape)
2. Responsiveness: Adapt to variable terminal widths
3. Error Handling: Display clear error messages with colors
4. Loading States: Show spinners and progress indicators

Styling Guidelines

1. Use semantic theme tokens instead of hardcoded colors
2. Prefer flexbox layouts over absolute positioning
3. Include proper margin and padding for visual hierarchy
4. Use truncation for long text with wrap="truncate-end"

Performance Considerations

1. Minimize re-renders with proper memoization
2. Use virtual scrolling for long lists
3. Lazy load heavy content (skill previews)
4. Cache discovery results when appropriate

Related Pages

Related topics: Terminal UI Components, Context and Memory Management

Session Management

Overview

Session Management in Gemini CLI provides persistent conversation contexts that enable users to resume work across CLI invocations, track project-specific interactions, and maintain stateful relationships between user prompts and model responses. The system orchestrates session lifecycle events including creation, storage, retrieval, resumption, and cleanup through an integrated stack spanning the core SDK, CLI UI components, and storage services.

Sessions serve as the fundamental unit of work in Gemini CLI, encapsulating all metadata and message history associated with a continuous interaction sequence. Each session is uniquely identified by a sessionId and tied to a specific project context via a projectHash, enabling the CLI to distinguish between multiple concurrent or historical conversations.

Sources: packages/core/src/services/chatRecordingService.ts:35-36

Session Lifecycle

graph TD
    A[User Starts CLI] --> B{Check for Existing Session?}
    B -->|Yes| C[Resume Session]
    B -->|No| D[Create New Session]
    D --> E[Generate Session ID]
    E --> F[Initialize Context Graph]
    F --> G[Start Conversation]
    C --> H[Load Session from Storage]
    H --> G
    G --> I[Process User Input]
    I --> J[Record Message to ChatHistory]
    J --> K{User Exits?}
    K -->|No| I
    K -->|Yes| L[Save Session Metadata]
    L --> M[Close Session]

Session Creation

When a user launches Gemini CLI without specifying an existing session, the system generates a new session identifier and initializes an empty conversation record. The session creation process involves:

1. Session ID Generation: A cryptographically stable session ID is created using the createSessionId() utility function. This ID persists across CLI restarts and is used to resume the same conversation.

1. Project Hash Computation: The system computes a hash of the current working directory to associate the session with a specific project context.

1. Storage Initialization: The ChatRecordingService prepares file-based storage at a project-specific temp directory, enabling conversation persistence.

Sources: packages/sdk/src/agent.ts:58-60

Session Resume

The session resume capability allows users to continue previous conversations seamlessly. When resuming a session, the system:

1. Loads the complete conversation history from JSONL storage
2. Reconstructs the context graph from stored messages
3. Validates authentication state
4. Restores model configuration and tool states

sequenceDiagram
    participant User
    participant CLI
    participant ChatRecordingService
    participant GeminiAgent
    
    User->>CLI: Resume Session (sessionId)
    CLI->>ChatRecordingService: Load Conversation Record
    ChatRecordingService-->>CLI: ConversationRecord (messages, metadata)
    CLI->>GeminiAgent: Initialize with Loaded State
    GeminiAgent-->>CLI: Session Ready
    CLI->>User: Display Last N Messages

Sources: packages/core/src/services/chatRecordingService.ts:45-52

Session Data Model

The ConversationRecord interface defines the complete structure of a persisted session:

Sources: packages/core/src/services/chatRecordingService.ts:32-50

Message Structure

Messages within a session follow the multi-part content model:

interface Message {
  role: 'user' | 'model' | 'system' | 'tool';
  parts: Array<{
    text?: string;
    functionCall?: FunctionCall;
    functionResponse?: FunctionResponse;
  }>;
}

The context graph builder processes each turn by:

1. Generating a stable MD5 hash from role and content for deduplication
2. Assigning an occurrence counter for repeated identical messages
3. Creating a stable turn ID using the getStableId() utility
4. Tracking function calls and responses with unique identifiers

Sources: packages/core/src/context/graph/toGraph.ts:1-30

Storage Architecture

Chat Recording Service

The ChatRecordingService class manages all session persistence operations:

graph LR
    A[In-Memory Cache] -->|Write-through| B[JSONL File]
    C[Session Load Request] --> D{Cache Hit?}
    D -->|Yes| A
    D -->|No| B
    B -->|Load| A

Key Responsibilities:

Sources: packages/core/src/services/chatRecordingService.ts:85-90

Storage Directory Structure

Sessions are stored in the project temp directory:

/tmp/gemini/
├── conversation-{sessionId}.jsonl   # Full message history
├── session-{sessionId}.json         # Session metadata
├── bug-report-history-{timestamp}.json  # Bug report exports
└── checkpoints/                     # Checkpoint snapshots

The getProjectTempDir() method determines the storage path based on the active project context.

Sources: packages/cli/src/ui/commands/bugCommand.test.ts:60-62

Session Browser Component

The SessionBrowser UI component provides an interactive interface for managing multiple sessions:

• Session List View: Displays all historical sessions for a project
• Session Preview: Shows message count, date range, and summary
• Session Actions: Resume, rename, delete, or export sessions
• Search/Filter: Find sessions by content or date

interface SessionBrowserProps {
  sessions: ConversationRecord[];
  onSelect: (sessionId: string) => void;
  onDelete: (sessionId: string) => Promise<void>;
  onExport: (sessionId: string) => Promise<void>;
}

Sources: packages/cli/src/ui/components/SessionBrowser.tsx

Rewind Viewer

The RewindViewer component enables users to navigate and review historical conversation states:

• Timeline Navigation: Move through conversation turns chronologically
• State Restoration: View message content at any past point
• Diff View: Compare changes between turns (optional)

This component leverages the turn-by-turn tracking implemented in the context graph builder to provide accurate historical snapshots.

Sources: packages/cli/src/ui/components/RewindViewer.tsx

Session Operations

The sessionOperations.ts utility module provides core session manipulation functions:

Available Operations

Session Resume Flow

graph TD
    A[Load Session Record] --> B{Valid Session?}
    B -->|No| C[Raise Error]
    B -->|Yes| D[Load Message History]
    D --> E[Reconstruct Context Graph]
    E --> F[Initialize Agent State]
    F --> G[Ready for User Input]

Sources: packages/core/src/utils/sessionOperations.ts

Context Graph Integration

The context graph system maintains the semantic structure of conversations independently from raw message storage:

1. Turn Tracking: Each user-model exchange is assigned a unique turn ID
2. Role Management: Messages are tagged with roles (user, model, tool, system)
3. Function Call Tracking: Tool interactions are recorded with unique IDs (call_{id} or resp_{id})
4. Legacy Header Handling: Automatically skips legacy environment headers during graph reconstruction

The graph builder generates stable identifiers using:

const turnContent = JSON.stringify(msg.parts);
const h = createHash('md5').update(`${msg.role}:${turnContent}`).digest('hex');
const occurrence = (seenHashes.get(h) || 0) + 1;
const turnSalt = `${h}_${occurrence}`;
const turnId = getStableId(msg, this.nodeIdentityMap, turnSalt, -1);

Sources: packages/core/src/context/graph/toGraph.ts:18-25

SDK Integration

The Gemini CLI SDK exposes session management through the GeminiCliAgent and GeminiCliSession classes:

const agent = new GeminiCliAgent({
  instructions: 'You are a helpful coding assistant.',
  tools: [myTool],
});

// Create a new session
const session = agent.session();
await session.initialize();

// Resume an existing session
const resumedSession = agent.session({ sessionId: 'existing-id' });
await resumedSession.initialize();

// Stream messages
for await (const event of session.sendStream('Hello!')) {
  console.log(event);
}

Sources: packages/sdk/src/agent.ts:35-55

About Box Display

Session metadata is surfaced in the CLI's About dialog:

Sources: packages/cli/src/ui/components/AboutBox.tsx:20-50

Configuration

Session-Related Settings

Bug Report Integration

When submitting bug reports via /bug, the session automatically exports chat history:

const history = geminiClient.getChat().getHistory();
const bugReportPath = path.join(
  storage.getProjectTempDir(),
  `bug-report-history-${Date.now()}.json`
);
await exportHistoryToFile({ history, filePath: bugReportPath });

The exported history includes the full conversation record and is attached to the GitHub issue for diagnostic purposes.

Sources: packages/cli/src/ui/commands/bugCommand.test.ts:45-65

Checkpointing

Sessions support checkpointing for disaster recovery and long-running task management:

• Automatic Checkpoints: Created at significant conversation milestones
• Manual Checkpoints: User-triggered via /checkpoint command
• Checkpoint Restoration: Resume from any saved checkpoint state

Checkpoints are stored alongside regular session data and include complete message history plus agent state snapshots.

Sources: docs/cli/checkpointing.md

Best Practices

1. Session Isolation: Each project should maintain its own session context
2. Regular Exports: Export important sessions before cleanup
3. Scratchpad Usage: Use the memory scratchpad for cross-session notes
4. Metadata Maintenance: Keep session summaries accurate for quick identification
5. Storage Cleanup: Periodically remove old sessions to conserve disk space

Related Commands

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: MCP servers not connected in -p (non-interactive) mode

• Severity: high
• Finding: Installation risk is backed by a source signal: MCP servers not connected in -p (non-interactive) mode. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/26021

2. Project risk: Stabilize and Enhance Internal Project Evaluations

• Severity: high
• Finding: Project risk is backed by a source signal: Stabilize and Enhance Internal Project Evaluations. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/23166

3. Security or permission risk: Developers should check this security_permissions risk before relying on the project: Add deterministic redaction and reduce Auto Memory logging

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: Add deterministic redaction and reduce Auto Memory logging
• User impact: Developers may expose sensitive permissions or credentials: Add deterministic redaction and reduce Auto Memory logging
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add deterministic redaction and reduce Auto Memory logging. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | fmev_aad664537e9ef9632034c0b355326a33 | https://github.com/google-gemini/gemini-cli/issues/26525 | Add deterministic redaction and reduce Auto Memory logging

4. Security or permission risk: Developers should check this security_permissions risk before relying on the project: Robust component level evalutions

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: Robust component level evalutions
• User impact: Developers may expose sensitive permissions or credentials: Robust component level evalutions
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Robust component level evalutions. Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | fmev_6de3f9226413accc4a19c695e4fdeb48 | https://github.com/google-gemini/gemini-cli/issues/24353 | Robust component level evalutions

5. Security or permission risk: Add deterministic redaction and reduce Auto Memory logging

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Add deterministic redaction and reduce Auto Memory logging. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/26525

6. Security or permission risk: Assess the impact of AST-aware file reads, search, and mapping

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Assess the impact of AST-aware file reads, search, and mapping. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/22745

7. Security or permission risk: Missing validation for critical configuration files could lead to broken bundles

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Missing validation for critical configuration files could lead to broken bundles. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/16114

8. Security or permission risk: Shell command execution gets stuck with "Waiting input" after command completes

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Shell command execution gets stuck with "Waiting input" after command completes. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/25166

9. Security or permission risk: Tracking: 429 / Capacity Issues

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Tracking: 429 / Capacity Issues. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/24937

10. Security or permission risk: [Bug] Proxy local bypass does not recognize environment variables

• Severity: high
• Finding: Security or permission risk is backed by a source signal: [Bug] Proxy local bypass does not recognize environment variables. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/23372

11. Security or permission risk: fata error again!

• Severity: high
• Finding: Security or permission risk is backed by a source signal: fata error again!. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/google-gemini/gemini-cli/issues/27084

12. Installation risk: Developers should check this installation risk before relying on the project: The CLI doesn't fall back to the system's ripgrep installation when the bundled one is missing

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: The CLI doesn't fall back to the system's ripgrep installation when the bundled one is missing
• User impact: Developers may fail before the first successful local run: The CLI doesn't fall back to the system's ripgrep installation when the bundled one is missing
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: The CLI doesn't fall back to the system's ripgrep installation when the bundled one is missing. Context: Observed when using macos
• Evidence: failure_mode_cluster:github_issue | fmev_5a9a3046d11e48e7d258f82489fe0315 | https://github.com/google-gemini/gemini-cli/issues/27192 | The CLI doesn't fall back to the system's ripgrep installation when the bundled one is missing

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using gemini-cli with real data or production workflows.

• Robust component level evalutions - github / github_issue
• Shell command execution gets stuck with "Waiting input" after command co - github / github_issue
• Surface or quarantine invalid Auto Memory inbox patches - github / github_issue
• Stop Auto Memory from retrying low-signal sessions indefinitely - github / github_issue
• Add deterministic redaction and reduce Auto Memory logging - github / github_issue
• gemini --resume cannot detect local history sessions - github / github_issue
• fata error again! - github / github_issue
• Missing validation for critical configuration files could lead to broken - github / github_issue
• Typing unmapped keys in Vim Normal mode inserts characters into input fi - github / github_issue
• [[Windows] run_shell_command always returns empty output — isBinary() fal](https://github.com/google-gemini/gemini-cli/issues/25164) - github / github_issue
• Gemini CLI should periodically reflect on the trajectory and recommend t - github / github_issue
• The write_file tool corrupts or truncates long text sequences during fil - github / github_issue