Core concepts

This guide explains the fundamental concepts and terminology used throughout the Gemini CLI ecosystem. Understanding these terms will help you make the most of the tool’s capabilities.

Approval mode

Approval mode determines the level of autonomy you grant to the agent when executing tools.

• Default: The agent asks for confirmation before performing any potentially impactful action (like writing files or running shell commands).
• Auto-edit: File modifications are applied automatically, but shell commands still require confirmation.
• YOLO (You Only Look Once): The agent runs all tools without asking for permission. High risk, high speed.

Checkpointing

Checkpointing is a safety feature that automatically snapshots your project’s file state before the agent performs any destructive action (like writing a file).

• Snapshots: Stored in a hidden Git repository (separate from your project’s Git history).
• Restore: Allows you to instantly revert changes if the agent makes a mistake, using the /restore command.

Context

Context refers to the information the agent has about your current task and environment. Gemini CLI provides context through several mechanisms:

• Conversation history: The chat log of the current session.
• Project context (GEMINI.md): Persistent instructions and rules defined in your project’s root or subdirectories.
• File content: Files you explicitly reference (e.g., @src/app.ts) or that the agent reads using tools.
• Environment: Information about your operating system, shell, and working directory.

Effective context management is key to getting accurate and relevant responses.

Extension

An Extension is a pluggable package that adds new capabilities to Gemini CLI. Extensions can bundle:

• Skills: Specialized procedural knowledge.
• MCP Servers: Connections to external tools and data.
• Commands: Custom slash commands.

Headless mode

Headless mode refers to running Gemini CLI without the interactive terminal UI (TUI). This is used for scripting, automation, and piping data into or out of the agent.

• Interactive: gemini (starts the REPL).
• Headless: gemini "Fix this file" (runs once and exits).

Hook

A Hook is a script or function that intercepts specific lifecycle events in the CLI.

• Use cases: Logging tool usage, validating user input, or modifying the agent’s system prompt dynamically.
• Lifecycle: Hooks can run before or after the agent starts, before tools are executed, or after the session ends.

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open standard that allows Gemini CLI to connect to external data sources and tools.

• MCP Server: A lightweight application that exposes resources (data) and tools (functions) to the CLI.
• Use case: Connecting Gemini to a PostgreSQL database, a GitHub repository, or a Slack workspace without building custom integration logic into the CLI core.

Policy engine

The Policy Engine is the security subsystem that enforces rules on tool execution. It evaluates every tool call against your configuration (e.g., Trusted folders, allowed commands) to decide whether to:

• Allow the action immediately.
• Require user confirmation.
• Block the action entirely.

Sandboxing

Sandboxing is an optional security mode that isolates the agent’s execution environment. When enabled, the agent runs inside a secure container (e.g., Docker), preventing it from accessing sensitive files or system resources outside of the designated workspace.

Session

A Session is a single continuous interaction thread with the agent.

• State: Sessions maintain conversation history and short-term memory.
• Persistence: Sessions are automatically saved, allowing you to pause, resume, or rewind them later.

Skill

A Skill (or Agent Skill) is a package of specialized expertise that the agent can load on demand. Unlike general context, a skill provides specific procedural knowledge for a distinct task.

• Example: A “Code Reviewer” skill might contain a checklist of security vulnerabilities to look for and a specific format for reporting findings.
• Activation: Skills are typically activated dynamically when the agent recognizes a matching request.

Tool

A Tool is a specific function or capability that the agent can execute. Tools allow the AI to interact with the outside world.

• Built-in tools: Core capabilities like read_file, run_shell_command, and google_web_search.
• MCP tools: External tools provided by MCP servers.

When the agent uses a tool, it pauses generation, executes the code, and feeds the output back into its context window.

Trusted folders

Trusted folders are specific directories you have explicitly authorized the agent to access without repeated confirmation prompts. This is a key component of the Policy engine to balance security and usability.