MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-06-16 22:36:48 -07:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'main' into mshanware/feat/btw

Browse Source
This commit is contained in:
cynthialong0-0
2026-04-21 14:08:39 -07:00
committed by GitHub
parent 4ce7968fa0 d6f88f8720
commit 320ec2c78c
569 changed files with 865150 additions and 8518 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/cli/acp-mode.md
+6 -6
View File
@@ -44,8 +44,8 @@ and Gemini CLI (the server).
- **Communication:** The entire communication happens over standard input/output
(stdio) using the JSON-RPC 2.0 protocol.
- **Client's role:** The client is responsible for sending requests (e.g.,
prompts) and handling responses and notifications from Gemini CLI.
- **Client's role:** The client is responsible for sending requests (for
example, prompts) and handling responses and notifications from Gemini CLI.
- **Gemini CLI's role:** In ACP mode, Gemini CLI listens for incoming JSON-RPC
requests, processes them, and sends back responses.
@@ -72,8 +72,8 @@ leverage the IDE's capabilities to perform tasks. The MCP client logic is in
## Capabilities and supported methods
The ACP protocol exposes a number of methods for ACP clients (e.g. IDEs) to
control Gemini CLI.
The ACP protocol exposes a number of methods for ACP clients (for example IDEs)
to control Gemini CLI.
### Core methods
@@ -87,8 +87,8 @@ control Gemini CLI.
### Session control
- `setSessionMode`: Allows changing the approval level for tool calls (e.g., to
`auto-approve`).
- `setSessionMode`: Allows changing the approval level for tool calls (for
example, to `auto-approve`).
- `unstable_setSessionModel`: Changes the model for the current session.
### File system proxy
docs/cli/auto-memory.md
+143
View File
@@ -0,0 +1,143 @@
# Auto Memory
Auto Memory is an experimental feature that mines your past Gemini CLI sessions
in the background and turns recurring workflows into reusable
[Agent Skills](./skills.md). You review, accept, or discard each extracted skill
before it becomes available to future sessions.
<!-- prettier-ignore -->
> [!NOTE]
> This is an experimental feature currently under active development.
## Overview
Every session you run with Gemini CLI is recorded locally as a transcript. Auto
Memory scans those transcripts for procedural patterns that recur across
sessions, then drafts each pattern as a `SKILL.md` file in a project-local
inbox. You inspect the draft, decide whether it captures real expertise, and
promote it to your global or workspace skills directory if you want it.
You'll use Auto Memory when you want to:
- **Capture team workflows** that you find yourself walking the agent through
more than once.
- **Codify hard-won fixes** for project-specific landmines so future sessions
avoid them.
- **Bootstrap a skills library** without writing every `SKILL.md` by hand.
Auto Memory complements—but does not replace—the
[`save_memory` tool](../tools/memory.md), which captures single facts into
`GEMINI.md`. Auto Memory captures multi-step procedures into skills.
## Prerequisites
- Gemini CLI installed and authenticated.
- At least 10 user messages across recent, idle sessions in the project. Auto
Memory ignores active or trivial sessions.
## How to enable Auto Memory
Auto Memory is off by default. Enable it in your settings file:
1. Open your global settings file at `~/.gemini/settings.json`. If you only
want Auto Memory in one project, edit `.gemini/settings.json` in that
project instead.
2. Add the experimental flag:
```json
{
"experimental": {
"autoMemory": true
}
}
```
3. Restart Gemini CLI. The flag requires a restart because the extraction
service starts during session boot.
## How Auto Memory works
Auto Memory runs as a background task on session startup. It does not block the
UI, consume your interactive turns, or surface tool prompts.
1. **Eligibility scan.** The service indexes recent sessions from
`~/.gemini/tmp/<project>/chats/`. Sessions are eligible only if they have
been idle for at least three hours and contain at least 10 user messages.
2. **Lock acquisition.** A lock file in the project's memory directory
coordinates across multiple CLI instances so extraction runs at most once at
a time.
3. **Sub-agent extraction.** A specialized sub-agent (named `confucius`)
reviews the session index, reads any sessions that look like they contain
repeated procedural workflows, and drafts new `SKILL.md` files. Its
instructions tell it to default to creating zero skills unless the evidence
is strong, so most runs produce no inbox items.
4. **Patch validation.** If the sub-agent proposes edits to skills outside the
inbox (for example, an existing global skill), it writes a unified diff
`.patch` file. Auto Memory dry-runs each patch and discards any that do not
apply cleanly.
5. **Notification.** When a run produces new skills or patches, Gemini CLI
surfaces an inline message telling you how many items are waiting.
## How to review extracted skills
Use the `/memory inbox` slash command to open the inbox dialog at any time:
**Command:** `/memory inbox`
The dialog lists each draft skill with its name, description, and source
sessions. From there you can:
- **Read** the full `SKILL.md` body before deciding.
- **Promote** a skill to your user (`~/.gemini/skills/`) or workspace
(`.gemini/skills/`) directory.
- **Discard** a skill you do not want.
- **Apply** or reject a `.patch` proposal against an existing skill.
Promoted skills become discoverable in the next session and follow the standard
[skill discovery precedence](./skills.md#skill-discovery-tiers).
## How to disable Auto Memory
To turn off background extraction, set the flag back to `false` in your settings
file and restart Gemini CLI:
```json
{
"experimental": {
"autoMemory": false
}
}
```
Disabling the flag stops the background service immediately on the next session
start. Existing inbox items remain on disk; you can either drain them with
`/memory inbox` first or remove the project memory directory manually.
## Data and privacy
- Auto Memory only reads session files that already exist locally on your
machine. Nothing is uploaded to Gemini outside the normal API calls the
extraction sub-agent makes during its run.
- The sub-agent is instructed to redact secrets, tokens, and credentials it
encounters and to never copy large tool outputs verbatim.
- Drafted skills live in your project's memory directory until you promote or
discard them. They are not automatically loaded into any session.
## Limitations
- The sub-agent runs on a preview Gemini Flash model. Extraction quality depends
on the model's ability to recognize durable patterns versus one-off incidents.
- Auto Memory does not extract skills from the current session. It only
considers sessions that have been idle for three hours or more.
- Inbox items are stored per project. Skills extracted in one workspace are not
visible from another until you promote them to the user-scope skills
directory.
## Next steps
- Learn how skills are discovered and activated in [Agent Skills](./skills.md).
- Explore the [memory management tutorial](./tutorials/memory-management.md) for
the complementary `save_memory` and `GEMINI.md` workflows.
- Review the experimental settings catalog in
[Settings](./settings.md#experimental).
docs/cli/checkpointing.md
+5 -5
View File
@@ -1,9 +1,9 @@
# Checkpointing
The Gemini CLI includes a Checkpointing feature that automatically saves a
snapshot of your project's state before any file modifications are made by
AI-powered tools. This lets you safely experiment with and apply code changes,
knowing you can instantly revert back to the state before the tool was run.
Gemini CLI includes a Checkpointing feature that automatically saves a snapshot
of your project's state before any file modifications are made by AI-powered
tools. This lets you safely experiment with and apply code changes, knowing you
can instantly revert back to the state before the tool was run.
## How it works
@@ -72,7 +72,7 @@ To see a list of all saved checkpoints for the current project, simply run:
The CLI will display a list of available checkpoint files. These file names are
typically composed of a timestamp, the name of the file being modified, and the
name of the tool that was about to be run (e.g.,
name of the tool that was about to be run (for example,
`2025-06-22T10-00-00_000Z-my-file.txt-write_file`).
### Restore a specific checkpoint
docs/cli/cli-reference.md
+11 -11
View File
@@ -29,16 +29,16 @@ and parameters.
These commands are available within the interactive REPL.
| Command | Description |
| -------------------- | ---------------------------------------- |
| `/skills reload` | Reload discovered skills from disk |
| `/agents reload` | Reload the agent registry |
| `/commands reload` | Reload custom slash commands |
| `/memory reload` | Reload context files (e.g., `GEMINI.md`) |
| `/mcp reload` | Restart and reload MCP servers |
| `/extensions reload` | Reload all active extensions |
| `/help` | Show help for all commands |
| `/quit` | Exit the interactive session |
| Command | Description |
| -------------------- | ----------------------------------------------- |
| `/skills reload` | Reload discovered skills from disk |
| `/agents reload` | Reload the agent registry |
| `/commands reload` | Reload custom slash commands |
| `/memory reload` | Reload context files (for example, `GEMINI.md`) |
| `/mcp reload` | Restart and reload MCP servers |
| `/extensions reload` | Reload all active extensions |
| `/help` | Show help for all commands |
| `/quit` | Exit the interactive session |
## CLI Options
@@ -60,7 +60,7 @@ These commands are available within the interactive REPL.
| `--allowed-tools` | - | array | - | **Deprecated.** Use the [Policy Engine](../reference/policy-engine.md) instead. Tools that are allowed to run without confirmation (comma-separated or multiple flags) |
| `--extensions` | `-e` | array | - | List of extensions to use. If not provided, all extensions are enabled (comma-separated or multiple flags) |
| `--list-extensions` | `-l` | boolean | - | List all available extensions and exit |
| `--resume` | `-r` | string | - | Resume a previous session. Use `"latest"` for most recent or index number (e.g. `--resume 5`) |
| `--resume` | `-r` | string | - | Resume a previous session. Use `"latest"` for most recent or index number (for example `--resume 5`) |
| `--list-sessions` | - | boolean | - | List available sessions for the current project and exit |
| `--delete-session` | - | string | - | Delete a session by index number (use `--list-sessions` to see available sessions) |
| `--include-directories` | - | array | - | Additional directories to include in the workspace (comma-separated or multiple flags) |
docs/cli/creating-skills.md
+2 -2
View File
@@ -14,7 +14,7 @@ skill. To use it, ask Gemini CLI to create a new skill for you.
Gemini CLI will then use the `skill-creator` to generate the skill:
1. Generate a new directory for your skill (e.g., `my-new-skill/`).
1. Generate a new directory for your skill (for example, `my-new-skill/`).
2. Create a `SKILL.md` file with the necessary YAML frontmatter (`name` and
`description`).
3. Create the standard resource directories: `scripts/`, `references/`, and
@@ -24,7 +24,7 @@ Gemini CLI will then use the `skill-creator` to generate the skill:
If you prefer to create skills manually:
1. **Create a directory** for your skill (e.g., `my-new-skill/`).
1. **Create a directory** for your skill (for example, `my-new-skill/`).
2. **Create a `SKILL.md` file** inside the new directory.
To add additional resources that support the skill, refer to the skill
docs/cli/custom-commands.md
+15 -14
View File
@@ -85,8 +85,8 @@ The model receives:
**B. Using arguments in shell commands (inside `!{...}` blocks)**
When you use `{{args}}` inside a shell injection block (`!{...}`), the arguments
are automatically **shell-escaped** before replacement. This allows you to
safely pass arguments to shell commands, ensuring the resulting command is
are automatically **shell-escaped** before replacement. This lets you safely
pass arguments to shell commands, ensuring the resulting command is
syntactically correct and secure while preventing command injection
vulnerabilities.
@@ -105,8 +105,8 @@ When you run `/grep-code It's complicated`:
1. The CLI sees `{{args}}` used both outside and inside `!{...}`.
2. Outside: The first `{{args}}` is replaced raw with `It's complicated`.
3. Inside: The second `{{args}}` is replaced with the escaped version (e.g., on
Linux: `"It\'s complicated"`).
3. Inside: The second `{{args}}` is replaced with the escaped version (for
example, on Linux: `"It\'s complicated"`).
4. The command executed is `grep -r "It's complicated" .`.
5. The CLI prompts you to confirm this exact, secure command before execution.
6. The final prompt is sent.
@@ -116,13 +116,13 @@ When you run `/grep-code It's complicated`:
If your `prompt` does **not** contain the special placeholder `{{args}}`, the
CLI uses a default behavior for handling arguments.
If you provide arguments to the command (e.g., `/mycommand arg1`), the CLI will
append the full command you typed to the end of the prompt, separated by two
newlines. This allows the model to see both the original instructions and the
specific arguments you just provided.
If you provide arguments to the command (for example, `/mycommand arg1`), the
CLI will append the full command you typed to the end of the prompt, separated
by two newlines. This allows the model to see both the original instructions and
the specific arguments you just provided.
If you do **not** provide any arguments (e.g., `/mycommand`), the prompt is sent
to the model exactly as it is, with nothing appended.
If you do **not** provide any arguments (for example, `/mycommand`), the prompt
is sent to the model exactly as it is, with nothing appended.
**Example (`changelog.toml`):**
@@ -188,7 +188,7 @@ ensure that only intended commands can be run.
dialog will appear showing the exact command(s) to be executed.
5. **Execution and error reporting:** The command is executed. If the command
fails, the output injected into the prompt will include the error messages
(stderr) followed by a status line, e.g.,
(stderr) followed by a status line, for example,
`[Shell command exited with code 1]`. This helps the model understand the
context of the failure.
@@ -229,9 +229,10 @@ operate on specific files.
- **File injection**: `@{path/to/file.txt}` is replaced by the content of
`file.txt`.
- **Multimodal support**: If the path points to a supported image (e.g., PNG,
JPEG), PDF, audio, or video file, it will be correctly encoded and injected as
multimodal input. Other binary files are handled gracefully and skipped.
- **Multimodal support**: If the path points to a supported image (for example,
PNG, JPEG), PDF, audio, or video file, it will be correctly encoded and
injected as multimodal input. Other binary files are handled gracefully and
skipped.
- **Directory listing**: `@{path/to/dir}` is traversed and each file present
within the directory and all subdirectories is inserted into the prompt. This
respects `.gitignore` and `.geminiignore` if enabled.
docs/cli/enterprise.md
+17 -14
View File
@@ -175,8 +175,8 @@ the enterprise settings are always loaded with the highest precedence.
**Example wrapper script:**
Administrators can create a script named `gemini` and place it in a directory
that appears earlier in the user's `PATH` than the actual Gemini CLI binary
(e.g., `/usr/local/bin/gemini`).
that appears earlier in the user's `PATH` than the actual Gemini CLI binary (for
example, `/usr/local/bin/gemini`).
```bash
#!/bin/bash
@@ -325,9 +325,9 @@ User. When it comes to the `mcpServers` object, these configurations are
1. **Merging:** The lists of servers from all three levels are combined into a
single list.
2. **Precedence:** If a server with the **same name** is defined at multiple
levels (e.g., a server named `corp-api` exists in both system and user
settings), the definition from the highest-precedence level is used. The
order of precedence is: **System > Workspace > User**.
levels (for example, a server named `corp-api` exists in both system and
user settings), the definition from the highest-precedence level is used.
The order of precedence is: **System > Workspace > User**.
This means a user **cannot** override the definition of a server that is already
defined in the system-level settings. However, they **can** add new servers with
@@ -343,8 +343,8 @@ canonical servers and adding their names to an allowlist.
For even greater security, especially when dealing with third-party MCP servers,
you can restrict which specific tools from a server are exposed to the model.
This is done using the `includeTools` and `excludeTools` properties within a
server's definition. This allows you to use a subset of tools from a server
without allowing potentially dangerous ones.
server's definition. This lets you use a subset of tools from a server without
allowing potentially dangerous ones.
Following the principle of least privilege, it is highly recommended to use
`includeTools` to create an allowlist of only the necessary tools.
@@ -481,9 +481,8 @@ an environment variable, but it can also be enforced for custom tools via the
## Telemetry and auditing
For auditing and monitoring purposes, you can configure Gemini CLI to send
telemetry data to a central location. This allows you to track tool usage and
other events. For more information, see the
[telemetry documentation](./telemetry.md).
telemetry data to a central location. This lets you track tool usage and other
events. For more information, see the [telemetry documentation](./telemetry.md).
**Example:** Enable telemetry and send it to a local OTLP collector. If
`otlpEndpoint` is not specified, it defaults to `http://localhost:4317`.
@@ -506,15 +505,19 @@ other events. For more information, see the
## Authentication
You can enforce a specific authentication method for all users by setting the
`enforcedAuthType` in the system-level `settings.json` file. This prevents users
from choosing a different authentication method. See the
[Authentication docs](../get-started/authentication.md) for more details.
`security.auth.enforcedType` in the system-level `settings.json` file. This
prevents users from choosing a different authentication method. See the
[Authentication docs](../get-started/authentication.mdx) for more details.
**Example:** Enforce the use of Google login for all users.
```json
{
"enforcedAuthType": "oauth-personal"
"security": {
"auth": {
"enforcedType": "oauth-personal"
}
}
}
```
docs/cli/gemini-ignore.md
+2 -2
View File
@@ -1,9 +1,9 @@
# Ignoring files
This document provides an overview of the Gemini Ignore (`.geminiignore`)
feature of the Gemini CLI.
feature of Gemini CLI.
The Gemini CLI includes the ability to automatically ignore files, similar to
Gemini CLI includes the ability to automatically ignore files, similar to
`.gitignore` (used by Git) and `.aiexclude` (used by Gemini Code Assist). Adding
paths to your `.geminiignore` file will exclude them from tools that support
this feature, although they will still be visible to other services (such as
docs/cli/generation-settings.md
+21 -19
View File
@@ -1,26 +1,28 @@
# Advanced Model Configuration
This guide details the Model Configuration system within the Gemini CLI.
Designed for researchers, AI quality engineers, and advanced users, this system
provides a rigorous framework for managing generative model hyperparameters and
This guide details the Model Configuration system within Gemini CLI. Designed
for researchers, AI quality engineers, and advanced users, this system provides
a rigorous framework for managing generative model hyperparameters and
behaviors.
> **Warning**: This is a power-user feature. Configuration values are passed
<!-- prettier-ignore -->
> [!WARNING]
> This is a power-user feature. Configuration values are passed
> directly to the model provider with minimal validation. Incorrect settings
> (e.g., incompatible parameter combinations) may result in runtime errors from
> the API.
> (for example, incompatible parameter combinations) may result in runtime
> errors from the API.
## 1. System Overview
The Model Configuration system (`ModelConfigService`) enables deterministic
control over model generation. It decouples the requested model identifier
(e.g., a CLI flag or agent request) from the underlying API configuration. This
allows for:
control over model generation. It decouples the requested model identifier (for
example, a CLI flag or agent request) from the underlying API configuration.
This allows for:
- **Precise Hyperparameter Tuning**: Direct control over `temperature`, `topP`,
`thinkingBudget`, and other SDK-level parameters.
- **Environment-Specific Behavior**: Distinct configurations for different
operating contexts (e.g., testing vs. production).
operating contexts (for example, testing vs. production).
- **Agent-Scoped Customization**: Applying specific settings only when a
particular agent is active.
@@ -71,7 +73,7 @@ context. They are evaluated dynamically for each model request.
specified `match` properties.
- `model`: Matches the requested model name or alias.
- `overrideScope`: Matches the distinct scope of the request (typically the
agent name, e.g., `codebaseInvestigator`).
agent name, for example, `codebaseInvestigator`).
**Example Override**:
@@ -113,8 +115,8 @@ and `overrideScope`).
1. **Filtering**: All matching overrides are identified.
2. **Sorting**: Matches are prioritized by **specificity** (the number of
matched keys in the `match` object).
- Specific matches (e.g., `model` + `overrideScope`) override broad matches
(e.g., `model` only).
- Specific matches (for example, `model` + `overrideScope`) override broad
matches (for example, `model` only).
- Tie-breaking: If specificity is equal, the order of definition in the
`overrides` array is preserved (last one wins).
3. **Merging**: The configurations from the sorted overrides are merged
@@ -128,10 +130,10 @@ The configuration follows the `ModelConfigServiceConfig` interface.
Defines the actual parameters for the model.
| Property | Type | Description |
| :---------------------- | :------- | :----------------------------------------------------------------- |
| `model` | `string` | The identifier of the model to be called (e.g., `gemini-2.5-pro`). |
| `generateContentConfig` | `object` | The configuration object passed to the `@google/genai` SDK. |
| Property | Type | Description |
| :---------------------- | :------- | :------------------------------------------------------------------------ |
| `model` | `string` | The identifier of the model to be called (for example, `gemini-2.5-pro`). |
| `generateContentConfig` | `object` | The configuration object passed to the `@google/genai` SDK. |
### `GenerateContentConfig` (Common Parameters)
@@ -142,7 +144,7 @@ Directly maps to the SDK's `GenerateContentConfig`. Common parameters include:
- **`topP`**: (`number`) Nucleus sampling probability.
- **`maxOutputTokens`**: (`number`) Limit on generated response length.
- **`thinkingConfig`**: (`object`) Configuration for models with reasoning
capabilities (e.g., `thinkingBudget`, `includeThoughts`).
capabilities (for example, `thinkingBudget`, `includeThoughts`).
## 5. Practical Examples
@@ -170,7 +172,7 @@ configuration but enforcing zero temperature.
### Agent-Specific Parameter Injection
Enforce extended thinking budgets for a specific agent without altering the
global default, e.g. for the `codebaseInvestigator`.
global default, for example for the `codebaseInvestigator`.
```json
"modelConfigs": {
docs/cli/model-routing.md
+2 -2
View File
@@ -10,8 +10,8 @@ Model routing is managed by the `ModelAvailabilityService`, which monitors model
health and automatically routes requests to available models based on defined
policies.
1. **Model failure:** If the currently selected model fails (e.g., due to quota
or server errors), the CLI will initiate the fallback process.
1. **Model failure:** If the currently selected model fails (for example, due
to quota or server errors), the CLI will initiate the fallback process.
2. **User consent:** Depending on the failure and the model's policy, the CLI
may prompt you to switch to a fallback model (by default always prompts
docs/cli/model-steering.md
+1 -1
View File
@@ -19,7 +19,7 @@ Model steering is an experimental feature and is disabled by default. You can
enable it using the `/settings` command or by updating your `settings.json`
file.
1. Type `/settings` in the Gemini CLI.
1. Type `/settings` in Gemini CLI.
2. Search for **Model Steering**.
3. Set the value to **true**.
docs/cli/plan-mode.md
+15 -6
View File
@@ -130,7 +130,9 @@ These are the only allowed tools:
[`cli_help`](../core/subagents.md#cli-help-agent)
- **Interaction:** [`ask_user`](../tools/ask-user.md)
- **MCP tools (Read):** Read-only [MCP tools](../tools/mcp-server.md) (for
example, `github_read_issue`, `postgres_read_schema`) are allowed.
example, `github_read_issue`, `postgres_read_schema`) and core
[MCP resource tools](../tools/mcp-resources.md) (`list_mcp_resources`,
`read_mcp_resource`) are allowed.
- **Planning (Write):**
[`write_file`](../tools/file-system.md#3-write_file-writefile) and
[`replace`](../tools/file-system.md#6-replace-edit) only allowed for `.md`
@@ -314,8 +316,8 @@ Hooks such as `BeforeTool` or `AfterTool` can be configured to intercept the
> [!WARNING] When hooks are triggered by **tool executions**, they do **not**
> run when you manually toggle Plan Mode using the `/plan` command or the
> `Shift+Tab` keyboard shortcut. If you need hooks to execute on mode changes,
> ensure the transition is initiated by the agent (e.g., by asking "start a plan
> for...").
> ensure the transition is initiated by the agent (for example, by asking "start
> a plan for...").
#### Example: Archive approved plans to GCS (`AfterTool`)
@@ -327,8 +329,11 @@ Storage whenever Gemini CLI exits Plan Mode to start the implementation.
```bash
#!/usr/bin/env bash
# Extract the plan path from the tool input JSON
plan_path=$(jq -r '.tool_input.plan_path // empty')
# Extract the plan filename from the tool input JSON
plan_filename=$(jq -r '.tool_input.plan_filename // empty')
# Construct the absolute path using the GEMINI_PLANS_DIR environment variable
plan_path="$GEMINI_PLANS_DIR/$plan_filename"
if [ -f "$plan_path" ]; then
# Generate a unique filename using a timestamp
@@ -354,7 +359,7 @@ To register this `AfterTool` hook, add it to your `settings.json`:
{
"name": "archive-plan",
"type": "command",
"command": "./.gemini/hooks/archive-plan.sh"
"command": "~/.gemini/hooks/archive-plan.sh"
}
]
}
@@ -441,6 +446,10 @@ on the current phase of your task:
switches to a high-speed **Flash** model. This provides a faster, more
responsive experience during the implementation of the plan.
If the high-reasoning model is unavailable or you don't have access to it,
Gemini CLI automatically and silently falls back to a faster model to ensure
your workflow isn't interrupted.
This behavior is enabled by default to provide the best balance of quality and
performance. You can disable this automatic switching in your settings:
docs/cli/sandbox.md
+7 -5
View File
@@ -1,11 +1,11 @@
# Sandboxing in the Gemini CLI
# Sandboxing in Gemini CLI
This document provides a guide to sandboxing in the Gemini CLI, including
This document provides a guide to sandboxing in Gemini CLI, including
prerequisites, quickstart, and configuration.
## Prerequisites
Before using sandboxing, you need to install and set up the Gemini CLI:
Before using sandboxing, you need to install and set up Gemini CLI:
```bash
npm install -g @google/gemini-cli
@@ -229,7 +229,7 @@ gemini -p "run the test suite"
2. **Environment variable**:
`GEMINI_SANDBOX=true|docker|podman|sandbox-exec|runsc|lxc`
3. **Settings file**: `"sandbox": true` in the `tools` object of your
`settings.json` file (e.g., `{"tools": {"sandbox": true}}`).
`settings.json` file (for example, `{"tools": {"sandbox": true}}`).
### macOS Seatbelt profiles
@@ -309,7 +309,9 @@ $env:SANDBOX_SET_UID_GID="false" # Disable UID/GID mapping
**Missing commands**
- Add to custom Dockerfile.
- Add to a custom Dockerfile. Automatic `BUILD_SANDBOX` builds are only
available when running Gemini CLI from source; npm installs need a prebuilt
image instead.
- Install via `sandbox.bashrc`.
**Network issues**
docs/cli/settings.md
+30 -26
View File
@@ -24,20 +24,22 @@ they appear in the UI.
### General
| UI Label | Setting | Description | Default |
| ----------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Vim Mode | `general.vimMode` | Enable Vim keybindings | `false` |
| Default Approval Mode | `general.defaultApprovalMode` | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. YOLO mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo). | `"default"` |
| Enable Auto Update | `general.enableAutoUpdate` | Enable automatic updates. | `true` |
| Enable Notifications | `general.enableNotifications` | Enable run-event notifications for action-required prompts and session completion. | `false` |
| Enable Plan Mode | `general.plan.enabled` | Enable Plan Mode for read-only safety during planning. | `true` |
| Plan Directory | `general.plan.directory` | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode. | `undefined` |
| Plan Model Routing | `general.plan.modelRouting` | Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase. | `true` |
| Retry Fetch Errors | `general.retryFetchErrors` | Retry on "exception TypeError: fetch failed sending request" errors. | `true` |
| Max Chat Model Attempts | `general.maxAttempts` | Maximum number of attempts for requests to the main chat model. Cannot exceed 10. | `10` |
| Debug Keystroke Logging | `general.debugKeystrokeLogging` | Enable debug logging of keystrokes to the console. | `false` |
| Enable Session Cleanup | `general.sessionRetention.enabled` | Enable automatic session cleanup | `true` |
| Keep chat history | `general.sessionRetention.maxAge` | Automatically delete chats older than this time period (e.g., "30d", "7d", "24h", "1w") | `"30d"` |
| UI Label | Setting | Description | Default |
| ----------------------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
| Vim Mode | `general.vimMode` | Enable Vim keybindings | `false` |
| Default Approval Mode | `general.defaultApprovalMode` | The default approval mode for tool execution. 'default' prompts for approval, 'auto_edit' auto-approves edit tools, and 'plan' is read-only mode. YOLO mode (auto-approve all actions) can only be enabled via command line (--yolo or --approval-mode=yolo). | `"default"` |
| Enable Auto Update | `general.enableAutoUpdate` | Enable automatic updates. | `true` |
| Enable Terminal Notifications | `general.enableNotifications` | Enable terminal run-event notifications for action-required prompts and session completion. | `false` |
| Terminal Notification Method | `general.notificationMethod` | How to send terminal notifications. | `"auto"` |
| Enable Plan Mode | `general.plan.enabled` | Enable Plan Mode for read-only safety during planning. | `true` |
| Plan Directory | `general.plan.directory` | The directory where planning artifacts are stored. If not specified, defaults to the system temporary directory. A custom directory requires a policy to allow write access in Plan Mode. | `undefined` |
| Plan Model Routing | `general.plan.modelRouting` | Automatically switch between Pro and Flash models based on Plan Mode status. Uses Pro for the planning phase and Flash for the implementation phase. | `true` |
| Retry Fetch Errors | `general.retryFetchErrors` | Retry on "exception TypeError: fetch failed sending request" errors. | `true` |
| Max Chat Model Attempts | `general.maxAttempts` | Maximum number of attempts for requests to the main chat model. Cannot exceed 10. | `10` |
| Debug Keystroke Logging | `general.debugKeystrokeLogging` | Enable debug logging of keystrokes to the console. | `false` |
| Enable Session Cleanup | `general.sessionRetention.enabled` | Enable automatic session cleanup | `true` |
| Keep chat history | `general.sessionRetention.maxAge` | Automatically delete chats older than this time period (e.g., "30d", "7d", "24h", "1w") | `"30d"` |
| Topic & Update Narration | `general.topicUpdateNarration` | Enable the Topic & Update communication model for reduced chattiness and structured progress reporting. | `true` |
### Output
@@ -159,18 +161,20 @@ they appear in the UI.
### Experimental
| UI Label | Setting | Description | Default |
| ---------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Enable Git Worktrees | `experimental.worktrees` | Enable automated Git worktree management for parallel work. | `false` |
| Use OSC 52 Paste | `experimental.useOSC52Paste` | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
| Use OSC 52 Copy | `experimental.useOSC52Copy` | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
| Model Steering | `experimental.modelSteering` | Enable model steering (user hints) to guide the model during tool execution. | `false` |
| Direct Web Fetch | `experimental.directWebFetch` | Enable web fetch behavior that bypasses LLM summarization. | `false` |
| Memory Manager Agent | `experimental.memoryManager` | Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories. | `false` |
| Use the generalist profile to manage agent contexts. | `experimental.generalistProfile` | Suitable for general coding and software development tasks. | `false` |
| Enable Context Management | `experimental.contextManagement` | Enable logic for context management. | `false` |
| Topic & Update Narration | `experimental.topicUpdateNarration` | Enable the experimental Topic & Update communication model for reduced chattiness and structured progress reporting. | `false` |
| Enable /btw Side Inquiries | `experimental.btw` | Enable the experimental /btw side inquiry command for ephemeral, non-persisted chat turns. | `false` |
| UI Label | Setting | Description | Default |
| ---------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| Enable Git Worktrees | `experimental.worktrees` | Enable automated Git worktree management for parallel work. | `false` |
| Use OSC 52 Paste | `experimental.useOSC52Paste` | Use OSC 52 for pasting. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
| Use OSC 52 Copy | `experimental.useOSC52Copy` | Use OSC 52 for copying. This may be more robust than the default system when using remote terminal sessions (if your terminal is configured to allow it). | `false` |
| Model Steering | `experimental.modelSteering` | Enable model steering (user hints) to guide the model during tool execution. | `false` |
| Direct Web Fetch | `experimental.directWebFetch` | Enable web fetch behavior that bypasses LLM summarization. | `false` |
| Enable Gemma Model Router | `experimental.gemmaModelRouter.enabled` | Enable the Gemma Model Router (experimental). Requires a local endpoint serving Gemma via the Gemini API using LiteRT-LM shim. | `false` |
| Auto-start LiteRT Server | `experimental.gemmaModelRouter.autoStartServer` | Automatically start the LiteRT-LM server when Gemini CLI starts and the Gemma router is enabled. | `false` |
| Memory Manager Agent | `experimental.memoryManager` | Replace the built-in save_memory tool with a memory manager subagent that supports adding, removing, de-duplicating, and organizing memories. | `false` |
| Auto Memory | `experimental.autoMemory` | Automatically extract reusable skills from past sessions in the background. Review results with /memory inbox. | `false` |
| Use the generalist profile to manage agent contexts. | `experimental.generalistProfile` | Suitable for general coding and software development tasks. | `false` |
| Enable Context Management | `experimental.contextManagement` | Enable logic for context management. | `false` |
| Enable /btw Side Inquiries | `experimental.btw` | Enable the experimental /btw side inquiry command for ephemeral, non-persisted chat turns. | `false` |
### Skills
docs/cli/system-prompt.md
+8 -8
View File
@@ -24,7 +24,7 @@ project-specific behavior or create a customized persona.
You can set the environment variable temporarily in your shell, or persist it
via a `.gemini/.env` file. See
[Persisting Environment Variables](../get-started/authentication.md#persisting-environment-variables).
[Persisting Environment Variables](../get-started/authentication.mdx#persisting-environment-variables).
- Use the project default path (`.gemini/system.md`):
- `GEMINI_SYSTEM_MD=true` or `GEMINI_SYSTEM_MD=1`
@@ -35,7 +35,7 @@ via a `.gemini/.env` file. See
- `GEMINI_SYSTEM_MD=/absolute/path/to/my-system.md`
- Relative paths are supported and resolved from the current working
directory.
- Tilde expansion is supported (e.g., `~/my-system.md`).
- Tilde expansion is supported (for example, `~/my-system.md`).
- Disable the override (use built‑in prompt):
- `GEMINI_SYSTEM_MD=false` or `GEMINI_SYSTEM_MD=0` or unset the variable.
@@ -51,7 +51,7 @@ error with: `missing system prompt file '<path>'`.
- Create `.gemini/system.md`, then add to `.gemini/.env`:
- `GEMINI_SYSTEM_MD=1`
- Use a custom file under your home directory:
- `GEMINI_SYSTEM_MD=~/prompts/SYSTEM.md gemini`
- `GEMINI_SYSTEM_MD=~/prompts/system.md gemini`
## UI indicator
@@ -70,7 +70,7 @@ dynamically include built-in content:
- `${AvailableTools}`: Injects a bulleted list of all currently enabled tool
names.
- Tool Name Variables: Injects the actual name of a tool using the pattern:
`${toolName}_ToolName` (e.g., `${write_file_ToolName}`,
`${toolName}_ToolName` (for example, `${write_file_ToolName}`,
`${run_shell_command_ToolName}`).
This pattern is generated dynamically for all available tools.
@@ -102,17 +102,17 @@ safety and workflow rules.
This creates the file and writes the current built‑in system prompt to it.
## Best practices: SYSTEM.md vs GEMINI.md
## Best practices: system.md vs GEMINI.md
- SYSTEM.md (firmware):
- system.md (firmware):
- Non‑negotiable operational rules: safety, tool‑use protocols, approvals, and
mechanics that keep the CLI reliable.
- Stable across tasks and projects (or per project when needed).
- GEMINI.md (strategy):
- Persona, goals, methodologies, and project/domain context.
- Evolves per task; relies on SYSTEM.md for safe execution.
- Evolves per task; relies on system.md for safe execution.
Keep SYSTEM.md minimal but complete for safety and tool operation. Keep
Keep system.md minimal but complete for safety and tool operation. Keep
GEMINI.md focused on high‑level guidance and project specifics.
## Troubleshooting
docs/cli/telemetry.md
+18 -11
View File
@@ -35,17 +35,18 @@ The observability system provides:
You control telemetry behavior through the `.gemini/settings.json` file.
Environment variables can override these settings.
| Setting | Environment Variable | Description | Values | Default |
| -------------- | -------------------------------- | --------------------------------------------------- | ----------------- | ----------------------- |
| `enabled` | `GEMINI_TELEMETRY_ENABLED` | Enable or disable telemetry | `true`/`false` | `false` |
| `target` | `GEMINI_TELEMETRY_TARGET` | Where to send telemetry data | `"gcp"`/`"local"` | `"local"` |
| `otlpEndpoint` | `GEMINI_TELEMETRY_OTLP_ENDPOINT` | OTLP collector endpoint | URL string | `http://localhost:4317` |
| `otlpProtocol` | `GEMINI_TELEMETRY_OTLP_PROTOCOL` | OTLP transport protocol | `"grpc"`/`"http"` | `"grpc"` |
| `outfile` | `GEMINI_TELEMETRY_OUTFILE` | Save telemetry to file (overrides `otlpEndpoint`) | file path | - |
| `logPrompts` | `GEMINI_TELEMETRY_LOG_PROMPTS` | Include prompts in telemetry logs | `true`/`false` | `true` |
| `useCollector` | `GEMINI_TELEMETRY_USE_COLLECTOR` | Use external OTLP collector (advanced) | `true`/`false` | `false` |
| `useCliAuth` | `GEMINI_TELEMETRY_USE_CLI_AUTH` | Use CLI credentials for telemetry (GCP target only) | `true`/`false` | `false` |
| - | `GEMINI_CLI_SURFACE` | Optional custom label for traffic reporting | string | - |
| Setting | Environment Variable | Description | Values | Default |
| -------------- | --------------------------------- | --------------------------------------------------- | ----------------- | ----------------------- |
| `enabled` | `GEMINI_TELEMETRY_ENABLED` | Enable or disable telemetry | `true`/`false` | `false` |
| `traces` | `GEMINI_TELEMETRY_TRACES_ENABLED` | Enable detailed attribute tracing | `true`/`false` | `false` |
| `target` | `GEMINI_TELEMETRY_TARGET` | Where to send telemetry data | `"gcp"`/`"local"` | `"local"` |
| `otlpEndpoint` | `GEMINI_TELEMETRY_OTLP_ENDPOINT` | OTLP collector endpoint | URL string | `http://localhost:4317` |
| `otlpProtocol` | `GEMINI_TELEMETRY_OTLP_PROTOCOL` | OTLP transport protocol | `"grpc"`/`"http"` | `"grpc"` |
| `outfile` | `GEMINI_TELEMETRY_OUTFILE` | Save telemetry to file (overrides `otlpEndpoint`) | file path | - |
| `logPrompts` | `GEMINI_TELEMETRY_LOG_PROMPTS` | Include prompts in telemetry logs | `true`/`false` | `true` |
| `useCollector` | `GEMINI_TELEMETRY_USE_COLLECTOR` | Use external OTLP collector (advanced) | `true`/`false` | `false` |
| `useCliAuth` | `GEMINI_TELEMETRY_USE_CLI_AUTH` | Use CLI credentials for telemetry (GCP target only) | `true`/`false` | `false` |
| - | `GEMINI_CLI_SURFACE` | Optional custom label for traffic reporting | string | - |
**Note on boolean environment variables:** For boolean settings like `enabled`,
setting the environment variable to `true` or `1` enables the feature.
@@ -1235,6 +1236,12 @@ These metrics follow standard [OpenTelemetry GenAI semantic conventions].
Traces provide an "under-the-hood" view of agent and backend operations. Use
traces to debug tool interactions and optimize performance.
<!-- prettier-ignore -->
> [!NOTE]
> Detailed trace attributes (like full prompts and tool outputs) are disabled by default
> to minimize overhead. You must explicitly set `telemetry.traces` to `true` (or set
> `GEMINI_TELEMETRY_TRACES_ENABLED=true`) to capture them.
Every trace captures rich metadata via standard span attributes.
<details open>
docs/cli/themes.md
+2 -2
View File
@@ -117,8 +117,8 @@ least `background.primary`, `text.primary`, `text.secondary`, and the various
accent colors via `text.link`, `text.accent`, and `status` to ensure a cohesive
UI.
You can use either hex codes (e.g., `#FF0000`) **or** standard CSS color names
(e.g., `coral`, `teal`, `blue`) for any color value. See
You can use either hex codes (for example, `#FF0000`) **or** standard CSS color
names (for example, `coral`, `teal`, `blue`) for any color value. See
[CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords)
for a full list of supported names.
docs/cli/trusted-folders.md
+14 -14
View File
@@ -1,7 +1,7 @@
# Trusted Folders
The Trusted Folders feature is a security setting that gives you control over
which projects can use the full capabilities of the Gemini CLI. It prevents
which projects can use the full capabilities of Gemini CLI. It prevents
potentially malicious code from running by asking you to approve a folder before
the CLI loads any project-specific configurations from it.
@@ -24,12 +24,12 @@ Add the following to your user `settings.json` file:
## How it works: The trust dialog
Once the feature is enabled, the first time you run the Gemini CLI from a
folder, a dialog will automatically appear, prompting you to make a choice:
Once the feature is enabled, the first time you run Gemini CLI from a folder, a
dialog will automatically appear, prompting you to make a choice:
- **Trust folder**: Grants full trust to the current folder (e.g.,
- **Trust folder**: Grants full trust to the current folder (for example,
`my-project`).
- **Trust parent folder**: Grants trust to the parent directory (e.g.,
- **Trust parent folder**: Grants trust to the parent directory (for example,
`safe-projects`), which automatically trusts all of its subdirectories as
well. This is useful if you keep all your safe projects in one place.
- **Don't trust**: Marks the folder as untrusted. The CLI will operate in a
@@ -40,9 +40,9 @@ will only be asked once per folder.
## Understanding folder contents: The discovery phase
Before you make a choice, the Gemini CLI performs a **discovery phase** to scan
the folder for potential configurations. This information is displayed in the
trust dialog to help you make an informed decision.
Before you make a choice, Gemini CLI performs a **discovery phase** to scan the
folder for potential configurations. This information is displayed in the trust
dialog to help you make an informed decision.
The discovery UI lists the following categories of items found in the project:
@@ -63,16 +63,16 @@ attention:
settings, such as auto-approving certain tools or disabling the security
sandbox.
- **Discovery Errors**: If the CLI encounters issues while scanning the folder
(e.g., a malformed `settings.json` file), these errors will be displayed
prominently.
(for example, a malformed `settings.json` file), these errors will be
displayed prominently.
By reviewing these details, you can ensure that you only grant trust to projects
that you know are safe.
## Why trust matters: The impact of an untrusted workspace
When a folder is **untrusted**, the Gemini CLI runs in a restricted "safe mode"
to protect you. In this mode, the following features are disabled:
When a folder is **untrusted**, Gemini CLI runs in a restricted "safe mode" to
protect you. In this mode, the following features are disabled:
1. **Workspace settings are ignored**: The CLI will **not** load the
`.gemini/settings.json` file from the project. This prevents the loading of
@@ -97,8 +97,8 @@ to protect you. In this mode, the following features are disabled:
commands from .toml files, including both project-specific and global user
commands.
Granting trust to a folder unlocks the full functionality of the Gemini CLI for
that workspace.
Granting trust to a folder unlocks the full functionality of Gemini CLI for that
workspace.
## Managing your trust settings
docs/cli/tutorials/mcp-setup.md
+1 -1
View File
@@ -102,7 +102,7 @@ The agent will:
## Troubleshooting
- **Server won't start?** Try running the docker command manually in your
terminal to see if it prints an error (e.g., "image not found").
terminal to see if it prints an error (for example, "image not found").
- **Tools not found?** Run `/mcp reload` to force the CLI to re-query the server
for its capabilities.
docs/cli/tutorials/memory-management.md
+3 -1
View File
@@ -50,7 +50,7 @@ loaded into every conversation.
### Scenario: Using the hierarchy
Context is loaded hierarchically. This allows you to have general rules for
Context is loaded hierarchically. This lets you have general rules for
everything and specific rules for sub-projects.
1. **Global:** `~/.gemini/GEMINI.md` (Rules for _every_ project you work on).
@@ -124,3 +124,5 @@ immediately. Force a reload with:
- Explore the [Command reference](../../reference/commands.md) for more
`/memory` options.
- Read the technical spec for [Project context](../../cli/gemini-md.md).
- Try the experimental [Auto Memory](../auto-memory.md) feature to extract
reusable skills from your past sessions automatically.
docs/cli/tutorials/plan-mode-steering.md
+2 -2
View File
@@ -79,8 +79,8 @@ each step with higher confidence and fewer errors.
- **Steer early:** Providing feedback during the research phase is more
efficient than waiting for the final plan to be drafted.
- **Use for context:** Steering is a great way to provide knowledge that might
not be obvious from reading the code (e.g., "We are planning to deprecate this
module next month").
not be obvious from reading the code (for example, "We are planning to
deprecate this module next month").
## Next steps
docs/cli/tutorials/session-management.md
+1 -1
View File
@@ -35,7 +35,7 @@ browser.
This opens a searchable list of all your past sessions. You'll see:
- A timestamp (e.g., "2 hours ago").
- A timestamp (for example, "2 hours ago").
- The first user message (helping you identify the topic).
- The number of turns in the conversation.
docs/cli/tutorials/shell-commands.md
+1 -1
View File
@@ -58,7 +58,7 @@ watchers.
**Prompt:** `Start the React dev server in the background.`
Gemini will run the command (e.g., `npm run dev`) and detach it.
Gemini will run the command (for example, `npm run dev`) and detach it.
### Scenario: Viewing active shells
docs/cli/tutorials/task-planning.md
+3 -3
View File
@@ -7,7 +7,7 @@ progress with the todo list.
## Prerequisites
- Gemini CLI installed and authenticated.
- A complex task in mind (e.g., a multi-file refactor or new feature).
- A complex task in mind (for example, a multi-file refactor or new feature).
## Why use task planning?
@@ -58,7 +58,7 @@ Tell the agent to proceed.
As the agent works, you'll see the todo list update in real-time above the input
box.
- **Current focus:** The active task is highlighted (e.g.,
- **Current focus:** The active task is highlighted (for example,
`[IN_PROGRESS] Create tsconfig.json`).
- **Progress:** Completed tasks are marked as done.
@@ -90,4 +90,4 @@ living document, not a static text block.
- See the [Todo tool reference](../../tools/todos.md) for technical schema
details.
- Learn about [Memory management](memory-management.md) to persist planning
preferences (e.g., "Always create a test plan first").
preferences (for example, "Always create a test plan first").