MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-03-10 14:10:37 -07:00
Code Issues Packages Projects Releases Wiki Activity

Remove unused files and update index and sidebar. (#19479)

Browse Source
This commit is contained in:
Sam Roberts
2026-02-18 16:10:49 -08:00
committed by GitHub
parent c62340675a
commit 04c52513e7
10 changed files with 81 additions and 1288 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
docs/core/concepts.md
View File

@@ -1,137 +0,0 @@
# 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](#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](#model-context-protocol-mcp).
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](#policy-engine) to balance security and usability.

76
docs/core/subagents.md
View File

@@ -1,13 +1,13 @@
# Sub-agents (experimental)
# Subagents (experimental)
Sub-agents are specialized agents that operate within your main Gemini CLI
Subagents are specialized agents that operate within your main Gemini CLI
session. They are designed to handle specific, complex tasks—like deep codebase
analysis, documentation lookup, or domain-specific reasoning—without cluttering
the main agent's context or toolset.
> **Note: Sub-agents are currently an experimental feature.**
> **Note: Subagents are currently an experimental feature.**
>
> To use custom sub-agents, you must explicitly enable them in your
> To use custom subagents, you must explicitly enable them in your
> `settings.json`:
>
> ```json
@@ -16,31 +16,31 @@ the main agent's context or toolset.
> }
> ```
>
> **Warning:** Sub-agents currently operate in
> **Warning:** Subagents currently operate in
> ["YOLO mode"](../get-started/configuration.md#command-line-arguments), meaning
> they may execute tools without individual user confirmation for each step.
> Proceed with caution when defining agents with powerful tools like
> `run_shell_command` or `write_file`.
## What are sub-agents?
## What are subagents?
Sub-agents are "specialists" that the main Gemini agent can hire for a specific
Subagents are "specialists" that the main Gemini agent can hire for a specific
job.
- **Focused context:** Each sub-agent has its own system prompt and persona.
- **Specialized tools:** Sub-agents can have a restricted or specialized set of
- **Focused context:** Each subagent has its own system prompt and persona.
- **Specialized tools:** Subagents can have a restricted or specialized set of
tools.
- **Independent context window:** Interactions with a sub-agent happen in a
- **Independent context window:** Interactions with a subagent happen in a
separate context loop, which saves tokens in your main conversation history.
Sub-agents are exposed to the main agent as a tool of the same name. When the
main agent calls the tool, it delegates the task to the sub-agent. Once the
sub-agent completes its task, it reports back to the main agent with its
Subagents are exposed to the main agent as a tool of the same name. When the
main agent calls the tool, it delegates the task to the subagent. Once the
subagent completes its task, it reports back to the main agent with its
findings.
## Built-in sub-agents
## Built-in subagents
Gemini CLI comes with the following built-in sub-agents:
Gemini CLI comes with the following built-in subagents:
### Codebase Investigator
@@ -75,15 +75,15 @@ Gemini CLI comes with the following built-in sub-agents:
### Generalist Agent
- **Name:** `generalist_agent`
- **Purpose:** Route tasks to the appropriate specialized sub-agent.
- **Purpose:** Route tasks to the appropriate specialized subagent.
- **When to use:** Implicitly used by the main agent for routing. Not directly
invoked by the user.
- **Configuration:** Enabled by default. No specific configuration options.
## Creating custom sub-agents
## Creating custom subagents
You can create your own sub-agents to automate specific workflows or enforce
specific personas. To use custom sub-agents, you must enable them in your
You can create your own subagents to automate specific workflows or enforce
specific personas. To use custom subagents, you must enable them in your
`settings.json`:
```json
@@ -138,20 +138,20 @@ it yourself; just report it.
### Configuration schema
| Field | Type | Required | Description |
| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------- |
| `name` | string | Yes | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores. |
| `description` | string | Yes | Short description of what the agent does. This is visible to the main agent to help it decide when to call this sub-agent. |
| `kind` | string | No | `local` (default) or `remote`. |
| `tools` | array | No | List of tool names this agent can use. If omitted, it may have access to a default set. |
| `model` | string | No | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model). |
| `temperature` | number | No | Model temperature (0.0 - 2.0). |
| `max_turns` | number | No | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`. |
| `timeout_mins` | number | No | Maximum execution time in minutes. Defaults to `5`. |
| Field | Type | Required | Description |
| :------------- | :----- | :------- | :------------------------------------------------------------------------------------------------------------------------ |
| `name` | string | Yes | Unique identifier (slug) used as the tool name for the agent. Only lowercase letters, numbers, hyphens, and underscores. |
| `description` | string | Yes | Short description of what the agent does. This is visible to the main agent to help it decide when to call this subagent. |
| `kind` | string | No | `local` (default) or `remote`. |
| `tools` | array | No | List of tool names this agent can use. If omitted, it may have access to a default set. |
| `model` | string | No | Specific model to use (e.g., `gemini-2.5-pro`). Defaults to `inherit` (uses the main session model). |
| `temperature` | number | No | Model temperature (0.0 - 2.0). |
| `max_turns` | number | No | Maximum number of conversation turns allowed for this agent before it must return. Defaults to `15`. |
| `timeout_mins` | number | No | Maximum execution time in minutes. Defaults to `5`. |
### Optimizing your sub-agent
### Optimizing your subagent
The main agent's system prompt encourages it to use an expert sub-agent when one
The main agent's system prompt encourages it to use an expert subagent when one
is available. It decides whether an agent is a relevant expert based on the
agent's description. You can improve the reliability with which an agent is used
by updating the description to more clearly indicate:
@@ -160,7 +160,7 @@ by updating the description to more clearly indicate:
- When it should be used.
- Some example scenarios.
For example, the following sub-agent description should be called fairly
For example, the following subagent description should be called fairly
consistently for Git operations.
> Git expert agent which should be used for all local and remote git operations.
@@ -170,13 +170,13 @@ consistently for Git operations.
> - Searching for regressions with bisect
> - Interacting with source control and issues providers such as GitHub.
If you need to further tune your sub-agent, you can do so by selecting the model
If you need to further tune your subagent, you can do so by selecting the model
to optimize for with `/model` and then asking the model why it does not think
that your sub-agent was called with a specific prompt and the given description.
that your subagent was called with a specific prompt and the given description.
## Remote subagents (Agent2Agent) (experimental)
Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent
Gemini CLI can also delegate tasks to remote subagents using the Agent-to-Agent
(A2A) protocol.
> **Note: Remote subagents are currently an experimental feature.**
@@ -184,8 +184,8 @@ Gemini CLI can also delegate tasks to remote sub-agents using the Agent-to-Agent
See the [Remote Subagents documentation](/docs/core/remote-agents) for detailed
configuration and usage instructions.
## Extension sub-agents
## Extension subagents
Extensions can bundle and distribute sub-agents. See the
[Extensions documentation](../extensions/index.md#sub-agents) for details on how
Extensions can bundle and distribute subagents. See the
[Extensions documentation](../extensions/index.md#subagents) for details on how
to package agents within an extension.