mirror of
https://github.com/google-gemini/gemini-cli.git
synced 2026-03-15 16:41:11 -07:00
Update sidebar.json and reference + resource files
This commit is contained in:
g-samroberts
@@ -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.
|
||||
@@ -1,246 +0,0 @@
|
||||
# Memory Import Processor
|
||||
|
||||
The Memory Import Processor is a feature that allows you to modularize your
|
||||
GEMINI.md files by importing content from other files using the `@file.md`
|
||||
syntax.
|
||||
|
||||
## Overview
|
||||
|
||||
This feature enables you to break down large GEMINI.md files into smaller, more
|
||||
manageable components that can be reused across different contexts. The import
|
||||
processor supports both relative and absolute paths, with built-in safety
|
||||
features to prevent circular imports and ensure file access security.
|
||||
|
||||
## Syntax
|
||||
|
||||
Use the `@` symbol followed by the path to the file you want to import:
|
||||
|
||||
```markdown
|
||||
# Main GEMINI.md file
|
||||
|
||||
This is the main content.
|
||||
|
||||
@./components/instructions.md
|
||||
|
||||
More content here.
|
||||
|
||||
@./shared/configuration.md
|
||||
```
|
||||
|
||||
## Supported path formats
|
||||
|
||||
### Relative paths
|
||||
|
||||
- `@./file.md` - Import from the same directory
|
||||
- `@../file.md` - Import from parent directory
|
||||
- `@./components/file.md` - Import from subdirectory
|
||||
|
||||
### Absolute paths
|
||||
|
||||
- `@/absolute/path/to/file.md` - Import using absolute path
|
||||
|
||||
## Examples
|
||||
|
||||
### Basic import
|
||||
|
||||
```markdown
|
||||
# My GEMINI.md
|
||||
|
||||
Welcome to my project!
|
||||
|
||||
@./get-started.md
|
||||
|
||||
## Features
|
||||
|
||||
@./features/overview.md
|
||||
```
|
||||
|
||||
### Nested imports
|
||||
|
||||
The imported files can themselves contain imports, creating a nested structure:
|
||||
|
||||
```markdown
|
||||
# main.md
|
||||
|
||||
@./header.md @./content.md @./footer.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
# header.md
|
||||
|
||||
# Project Header
|
||||
|
||||
@./shared/title.md
|
||||
```
|
||||
|
||||
## Safety features
|
||||
|
||||
### Circular import detection
|
||||
|
||||
The processor automatically detects and prevents circular imports:
|
||||
|
||||
```markdown
|
||||
# file-a.md
|
||||
|
||||
@./file-b.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
# file-b.md
|
||||
|
||||
@./file-a.md <!-- This will be detected and prevented -->
|
||||
```
|
||||
|
||||
### File access security
|
||||
|
||||
The `validateImportPath` function ensures that imports are only allowed from
|
||||
specified directories, preventing access to sensitive files outside the allowed
|
||||
scope.
|
||||
|
||||
### Maximum import depth
|
||||
|
||||
To prevent infinite recursion, there's a configurable maximum import depth
|
||||
(default: 5 levels).
|
||||
|
||||
## Error handling
|
||||
|
||||
### Missing files
|
||||
|
||||
If a referenced file doesn't exist, the import will fail gracefully with an
|
||||
error comment in the output.
|
||||
|
||||
### File access errors
|
||||
|
||||
Permission issues or other file system errors are handled gracefully with
|
||||
appropriate error messages.
|
||||
|
||||
## Code region detection
|
||||
|
||||
The import processor uses the `marked` library to detect code blocks and inline
|
||||
code spans, ensuring that `@` imports inside these regions are properly ignored.
|
||||
This provides robust handling of nested code blocks and complex Markdown
|
||||
structures.
|
||||
|
||||
## Import tree structure
|
||||
|
||||
The processor returns an import tree that shows the hierarchy of imported files,
|
||||
similar to Claude's `/memory` feature. This helps users debug problems with
|
||||
their GEMINI.md files by showing which files were read and their import
|
||||
relationships.
|
||||
|
||||
Example tree structure:
|
||||
|
||||
```
|
||||
Memory Files
|
||||
L project: GEMINI.md
|
||||
L a.md
|
||||
L b.md
|
||||
L c.md
|
||||
L d.md
|
||||
L e.md
|
||||
L f.md
|
||||
L included.md
|
||||
```
|
||||
|
||||
The tree preserves the order that files were imported and shows the complete
|
||||
import chain for debugging purposes.
|
||||
|
||||
## Comparison to Claude Code's `/memory` (`claude.md`) approach
|
||||
|
||||
Claude Code's `/memory` feature (as seen in `claude.md`) produces a flat, linear
|
||||
document by concatenating all included files, always marking file boundaries
|
||||
with clear comments and path names. It does not explicitly present the import
|
||||
hierarchy, but the LLM receives all file contents and paths, which is sufficient
|
||||
for reconstructing the hierarchy if needed.
|
||||
|
||||
> [!NOTE] The import tree is mainly for clarity during development and has
|
||||
> limited relevance to LLM consumption.
|
||||
|
||||
## API reference
|
||||
|
||||
### `processImports(content, basePath, debugMode?, importState?)`
|
||||
|
||||
Processes import statements in GEMINI.md content.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- `content` (string): The content to process for imports
|
||||
- `basePath` (string): The directory path where the current file is located
|
||||
- `debugMode` (boolean, optional): Whether to enable debug logging (default:
|
||||
false)
|
||||
- `importState` (ImportState, optional): State tracking for circular import
|
||||
prevention
|
||||
|
||||
**Returns:** Promise<ProcessImportsResult> - Object containing processed
|
||||
content and import tree
|
||||
|
||||
### `ProcessImportsResult`
|
||||
|
||||
```typescript
|
||||
interface ProcessImportsResult {
|
||||
content: string; // The processed content with imports resolved
|
||||
importTree: MemoryFile; // Tree structure showing the import hierarchy
|
||||
}
|
||||
```
|
||||
|
||||
### `MemoryFile`
|
||||
|
||||
```typescript
|
||||
interface MemoryFile {
|
||||
path: string; // The file path
|
||||
imports?: MemoryFile[]; // Direct imports, in the order they were imported
|
||||
}
|
||||
```
|
||||
|
||||
### `validateImportPath(importPath, basePath, allowedDirectories)`
|
||||
|
||||
Validates import paths to ensure they are safe and within allowed directories.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- `importPath` (string): The import path to validate
|
||||
- `basePath` (string): The base directory for resolving relative paths
|
||||
- `allowedDirectories` (string[]): Array of allowed directory paths
|
||||
|
||||
**Returns:** boolean - Whether the import path is valid
|
||||
|
||||
### `findProjectRoot(startDir)`
|
||||
|
||||
Finds the project root by searching for a `.git` directory upwards from the
|
||||
given start directory. Implemented as an **async** function using non-blocking
|
||||
file system APIs to avoid blocking the Node.js event loop.
|
||||
|
||||
**Parameters:**
|
||||
|
||||
- `startDir` (string): The directory to start searching from
|
||||
|
||||
**Returns:** Promise<string> - The project root directory (or the start
|
||||
directory if no `.git` is found)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use descriptive file names** for imported components
|
||||
2. **Keep imports shallow** - avoid deeply nested import chains
|
||||
3. **Document your structure** - maintain a clear hierarchy of imported files
|
||||
4. **Test your imports** - ensure all referenced files exist and are accessible
|
||||
5. **Use relative paths** when possible for better portability
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common issues
|
||||
|
||||
1. **Import not working**: Check that the file exists and the path is correct
|
||||
2. **Circular import warnings**: Review your import structure for circular
|
||||
references
|
||||
3. **Permission errors**: Ensure the files are readable and within allowed
|
||||
directories
|
||||
4. **Path resolution issues**: Use absolute paths if relative paths aren't
|
||||
resolving correctly
|
||||
|
||||
### Debug mode
|
||||
|
||||
Enable debug mode to see detailed logging of the import process:
|
||||
|
||||
```typescript
|
||||
const result = await processImports(content, basePath, true);
|
||||
```
|
||||
@@ -1,317 +0,0 @@
|
||||
# Policy engine
|
||||
|
||||
The Gemini CLI includes a powerful policy engine that provides fine-grained
|
||||
control over tool execution. It allows users and administrators to define rules
|
||||
that determine whether a tool call should be allowed, denied, or require user
|
||||
confirmation.
|
||||
|
||||
## Quick start
|
||||
|
||||
To create your first policy:
|
||||
|
||||
1. **Create the policy directory** if it doesn't exist:
|
||||
```bash
|
||||
mkdir -p ~/.gemini/policies
|
||||
```
|
||||
2. **Create a new policy file** (e.g., `~/.gemini/policies/my-rules.toml`). You
|
||||
can use any filename ending in `.toml`; all such files in this directory
|
||||
will be loaded and combined:
|
||||
```toml
|
||||
[[rule]]
|
||||
toolName = "run_shell_command"
|
||||
commandPrefix = "git status"
|
||||
decision = "allow"
|
||||
priority = 100
|
||||
```
|
||||
3. **Run a command** that triggers the policy (e.g., ask Gemini CLI to
|
||||
`git status`). The tool will now execute automatically without prompting for
|
||||
confirmation.
|
||||
|
||||
## Core concepts
|
||||
|
||||
The policy engine operates on a set of rules. Each rule is a combination of
|
||||
conditions and a resulting decision. When a large language model wants to
|
||||
execute a tool, the policy engine evaluates all rules to find the
|
||||
highest-priority rule that matches the tool call.
|
||||
|
||||
A rule consists of the following main components:
|
||||
|
||||
- **Conditions**: Criteria that a tool call must meet for the rule to apply.
|
||||
This can include the tool's name, the arguments provided to it, or the current
|
||||
approval mode.
|
||||
- **Decision**: The action to take if the rule matches (`allow`, `deny`, or
|
||||
`ask_user`).
|
||||
- **Priority**: A number that determines the rule's precedence. Higher numbers
|
||||
win.
|
||||
|
||||
For example, this rule will ask for user confirmation before executing any `git`
|
||||
command.
|
||||
|
||||
```toml
|
||||
[[rule]]
|
||||
toolName = "run_shell_command"
|
||||
commandPrefix = "git "
|
||||
decision = "ask_user"
|
||||
priority = 100
|
||||
```
|
||||
|
||||
### Conditions
|
||||
|
||||
Conditions are the criteria that a tool call must meet for a rule to apply. The
|
||||
primary conditions are the tool's name and its arguments.
|
||||
|
||||
#### Tool Name
|
||||
|
||||
The `toolName` in the rule must match the name of the tool being called.
|
||||
|
||||
- **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
|
||||
wildcard. A `toolName` of `my-server__*` will match any tool from the
|
||||
`my-server` MCP.
|
||||
|
||||
#### Arguments pattern
|
||||
|
||||
If `argsPattern` is specified, the tool's arguments are converted to a stable
|
||||
JSON string, which is then tested against the provided regular expression. If
|
||||
the arguments don't match the pattern, the rule does not apply.
|
||||
|
||||
### Decisions
|
||||
|
||||
There are three possible decisions a rule can enforce:
|
||||
|
||||
- `allow`: The tool call is executed automatically without user interaction.
|
||||
- `deny`: The tool call is blocked and is not executed.
|
||||
- `ask_user`: The user is prompted to approve or deny the tool call. (In
|
||||
non-interactive mode, this is treated as `deny`.)
|
||||
|
||||
### Priority system and tiers
|
||||
|
||||
The policy engine uses a sophisticated priority system to resolve conflicts when
|
||||
multiple rules match a single tool call. The core principle is simple: **the
|
||||
rule with the highest priority wins**.
|
||||
|
||||
To provide a clear hierarchy, policies are organized into three tiers. Each tier
|
||||
has a designated number that forms the base of the final priority calculation.
|
||||
|
||||
| Tier | Base | Description |
|
||||
| :------ | :--- | :------------------------------------------------------------------------- |
|
||||
| Default | 1 | Built-in policies that ship with the Gemini CLI. |
|
||||
| User | 2 | Custom policies defined by the user. |
|
||||
| Admin | 3 | Policies managed by an administrator (e.g., in an enterprise environment). |
|
||||
|
||||
Within a TOML policy file, you assign a priority value from **0 to 999**. The
|
||||
engine transforms this into a final priority using the following formula:
|
||||
|
||||
`final_priority = tier_base + (toml_priority / 1000)`
|
||||
|
||||
This system guarantees that:
|
||||
|
||||
- Admin policies always override User and Default policies.
|
||||
- User policies always override Default policies.
|
||||
- You can still order rules within a single tier with fine-grained control.
|
||||
|
||||
For example:
|
||||
|
||||
- A `priority: 50` rule in a Default policy file becomes `1.050`.
|
||||
- A `priority: 100` rule in a User policy file becomes `2.100`.
|
||||
- A `priority: 20` rule in an Admin policy file becomes `3.020`.
|
||||
|
||||
### Approval modes
|
||||
|
||||
Approval modes allow the policy engine to apply different sets of rules based on
|
||||
the CLI's operational mode. A rule can be associated with one or more modes
|
||||
(e.g., `yolo`, `autoEdit`, `plan`). The rule will only be active if the CLI is
|
||||
running in one of its specified modes. If a rule has no modes specified, it is
|
||||
always active.
|
||||
|
||||
- `default`: The standard interactive mode where most write tools require
|
||||
confirmation.
|
||||
- `autoEdit`: Optimized for automated code editing; some write tools may be
|
||||
auto-approved.
|
||||
- `plan`: A strict, read-only mode for research and design. See [Customizing
|
||||
Plan Mode Policies].
|
||||
- `yolo`: A mode where all tools are auto-approved (use with extreme caution).
|
||||
|
||||
## Rule matching
|
||||
|
||||
When a tool call is made, the engine checks it against all active rules,
|
||||
starting from the highest priority. The first rule that matches determines the
|
||||
outcome.
|
||||
|
||||
A rule matches a tool call if all of its conditions are met:
|
||||
|
||||
1. **Tool name**: The `toolName` in the rule must match the name of the tool
|
||||
being called.
|
||||
- **Wildcards**: For Model-hosting-protocol (MCP) servers, you can use a
|
||||
wildcard. A `toolName` of `my-server__*` will match any tool from the
|
||||
`my-server` MCP.
|
||||
2. **Arguments pattern**: If `argsPattern` is specified, the tool's arguments
|
||||
are converted to a stable JSON string, which is then tested against the
|
||||
provided regular expression. If the arguments don't match the pattern, the
|
||||
rule does not apply.
|
||||
|
||||
## Configuration
|
||||
|
||||
Policies are defined in `.toml` files. The CLI loads these files from Default,
|
||||
User, and (if configured) Admin directories.
|
||||
|
||||
### Policy locations
|
||||
|
||||
| Tier | Type | Location |
|
||||
| :-------- | :----- | :-------------------------- |
|
||||
| **User** | Custom | `~/.gemini/policies/*.toml` |
|
||||
| **Admin** | System | _See below (OS specific)_ |
|
||||
|
||||
#### System-wide policies (Admin)
|
||||
|
||||
Administrators can enforce system-wide policies (Tier 3) that override all user
|
||||
and default settings. These policies must be placed in specific, secure
|
||||
directories:
|
||||
|
||||
| OS | Policy Directory Path |
|
||||
| :---------- | :------------------------------------------------ |
|
||||
| **Linux** | `/etc/gemini-cli/policies` |
|
||||
| **macOS** | `/Library/Application Support/GeminiCli/policies` |
|
||||
| **Windows** | `C:\ProgramData\gemini-cli\policies` |
|
||||
|
||||
**Security Requirements:**
|
||||
|
||||
To prevent privilege escalation, the CLI enforces strict security checks on
|
||||
admin directories. If checks fail, system policies are **ignored**.
|
||||
|
||||
- **Linux / macOS:** Must be owned by `root` (UID 0) and NOT writable by group
|
||||
or others (e.g., `chmod 755`).
|
||||
- **Windows:** Must be in `C:\ProgramData`. Standard users (`Users`, `Everyone`)
|
||||
must NOT have `Write`, `Modify`, or `Full Control` permissions. _Tip: If you
|
||||
see a security warning, use the folder properties to remove write permissions
|
||||
for non-admin groups. You may need to "Disable inheritance" in Advanced
|
||||
Security Settings._
|
||||
|
||||
### TOML rule schema
|
||||
|
||||
Here is a breakdown of the fields available in a TOML policy rule:
|
||||
|
||||
```toml
|
||||
[[rule]]
|
||||
# A unique name for the tool, or an array of names.
|
||||
toolName = "run_shell_command"
|
||||
|
||||
# (Optional) The name of an MCP server. Can be combined with toolName
|
||||
# to form a composite name like "mcpName__toolName".
|
||||
mcpName = "my-custom-server"
|
||||
|
||||
# (Optional) A regex to match against the tool's arguments.
|
||||
argsPattern = '"command":"(git|npm)'
|
||||
|
||||
# (Optional) A string or array of strings that a shell command must start with.
|
||||
# This is syntactic sugar for `toolName = "run_shell_command"` and an `argsPattern`.
|
||||
commandPrefix = "git "
|
||||
|
||||
# (Optional) A regex to match against the entire shell command.
|
||||
# This is also syntactic sugar for `toolName = "run_shell_command"`.
|
||||
# Note: This pattern is tested against the JSON representation of the arguments (e.g., `{"command":"<your_command>"}`).
|
||||
# Because it prepends `"command":"`, it effectively matches from the start of the command.
|
||||
# Anchors like `^` or `$` apply to the full JSON string, so `^` should usually be avoided here.
|
||||
# You cannot use commandPrefix and commandRegex in the same rule.
|
||||
commandRegex = "git (commit|push)"
|
||||
|
||||
# The decision to take. Must be "allow", "deny", or "ask_user".
|
||||
decision = "ask_user"
|
||||
|
||||
# The priority of the rule, from 0 to 999.
|
||||
priority = 10
|
||||
|
||||
# (Optional) A custom message to display when a tool call is denied by this rule.
|
||||
# This message is returned to the model and user, useful for explaining *why* it was denied.
|
||||
deny_message = "Deletion is permanent"
|
||||
|
||||
# (Optional) An array of approval modes where this rule is active.
|
||||
modes = ["autoEdit"]
|
||||
```
|
||||
|
||||
### Using arrays (lists)
|
||||
|
||||
To apply the same rule to multiple tools or command prefixes, you can provide an
|
||||
array of strings for the `toolName` and `commandPrefix` fields.
|
||||
|
||||
**Example:**
|
||||
|
||||
This single rule will apply to both the `write_file` and `replace` tools.
|
||||
|
||||
```toml
|
||||
[[rule]]
|
||||
toolName = ["write_file", "replace"]
|
||||
decision = "ask_user"
|
||||
priority = 10
|
||||
```
|
||||
|
||||
### Special syntax for `run_shell_command`
|
||||
|
||||
To simplify writing policies for `run_shell_command`, you can use
|
||||
`commandPrefix` or `commandRegex` instead of the more complex `argsPattern`.
|
||||
|
||||
- `commandPrefix`: Matches if the `command` argument starts with the given
|
||||
string.
|
||||
- `commandRegex`: Matches if the `command` argument matches the given regular
|
||||
expression.
|
||||
|
||||
**Example:**
|
||||
|
||||
This rule will ask for user confirmation before executing any `git` command.
|
||||
|
||||
```toml
|
||||
[[rule]]
|
||||
toolName = "run_shell_command"
|
||||
commandPrefix = "git "
|
||||
decision = "ask_user"
|
||||
priority = 100
|
||||
```
|
||||
|
||||
### Special syntax for MCP tools
|
||||
|
||||
You can create rules that target tools from Model-hosting-protocol (MCP) servers
|
||||
using the `mcpName` field or a wildcard pattern.
|
||||
|
||||
**1. Using `mcpName`**
|
||||
|
||||
To target a specific tool from a specific server, combine `mcpName` and
|
||||
`toolName`.
|
||||
|
||||
```toml
|
||||
# Allows the `search` tool on the `my-jira-server` MCP
|
||||
[[rule]]
|
||||
mcpName = "my-jira-server"
|
||||
toolName = "search"
|
||||
decision = "allow"
|
||||
priority = 200
|
||||
```
|
||||
|
||||
**2. Using a wildcard**
|
||||
|
||||
To create a rule that applies to _all_ tools on a specific MCP server, specify
|
||||
only the `mcpName`.
|
||||
|
||||
```toml
|
||||
# Denies all tools from the `untrusted-server` MCP
|
||||
[[rule]]
|
||||
mcpName = "untrusted-server"
|
||||
decision = "deny"
|
||||
priority = 500
|
||||
deny_message = "This server is not trusted by the admin."
|
||||
```
|
||||
|
||||
## Default policies
|
||||
|
||||
The Gemini CLI ships with a set of default policies to provide a safe
|
||||
out-of-the-box experience.
|
||||
|
||||
- **Read-only tools** (like `read_file`, `glob`) are generally **allowed**.
|
||||
- **Agent delegation** defaults to **`ask_user`** to ensure remote agents can
|
||||
prompt for confirmation, but local sub-agent actions are executed silently and
|
||||
checked individually.
|
||||
- **Write tools** (like `write_file`, `run_shell_command`) default to
|
||||
**`ask_user`**.
|
||||
- In **`yolo`** mode, a high-priority rule allows all tools.
|
||||
- In **`autoEdit`** mode, rules allow certain write operations to happen without
|
||||
prompting.
|
||||
|
||||
[Customizing Plan Mode Policies]: /docs/cli/plan-mode.md#customizing-policies
|
||||
@@ -1,131 +0,0 @@
|
||||
# Gemini CLI core: Tools API
|
||||
|
||||
The Gemini CLI core (`packages/core`) features a robust system for defining,
|
||||
registering, and executing tools. These tools extend the capabilities of the
|
||||
Gemini model, allowing it to interact with the local environment, fetch web
|
||||
content, and perform various actions beyond simple text generation.
|
||||
|
||||
## Core concepts
|
||||
|
||||
- **Tool (`tools.ts`):** An interface and base class (`BaseTool`) that defines
|
||||
the contract for all tools. Each tool must have:
|
||||
- `name`: A unique internal name (used in API calls to Gemini).
|
||||
- `displayName`: A user-friendly name.
|
||||
- `description`: A clear explanation of what the tool does, which is provided
|
||||
to the Gemini model.
|
||||
- `parameterSchema`: A JSON schema defining the parameters that the tool
|
||||
accepts. This is crucial for the Gemini model to understand how to call the
|
||||
tool correctly.
|
||||
- `validateToolParams()`: A method to validate incoming parameters.
|
||||
- `getDescription()`: A method to provide a human-readable description of what
|
||||
the tool will do with specific parameters before execution.
|
||||
- `shouldConfirmExecute()`: A method to determine if user confirmation is
|
||||
required before execution (e.g., for potentially destructive operations).
|
||||
- `execute()`: The core method that performs the tool's action and returns a
|
||||
`ToolResult`.
|
||||
|
||||
- **`ToolResult` (`tools.ts`):** An interface defining the structure of a tool's
|
||||
execution outcome:
|
||||
- `llmContent`: The factual content to be included in the history sent back to
|
||||
the LLM for context. This can be a simple string or a `PartListUnion` (an
|
||||
array of `Part` objects and strings) for rich content.
|
||||
- `returnDisplay`: A user-friendly string (often Markdown) or a special object
|
||||
(like `FileDiff`) for display in the CLI.
|
||||
|
||||
- **Returning rich content:** Tools are not limited to returning simple text.
|
||||
The `llmContent` can be a `PartListUnion`, which is an array that can contain
|
||||
a mix of `Part` objects (for images, audio, etc.) and `string`s. This allows a
|
||||
single tool execution to return multiple pieces of rich content.
|
||||
|
||||
- **Tool registry (`tool-registry.ts`):** A class (`ToolRegistry`) responsible
|
||||
for:
|
||||
- **Registering tools:** Holding a collection of all available built-in tools
|
||||
(e.g., `ReadFileTool`, `ShellTool`).
|
||||
- **Discovering tools:** It can also discover tools dynamically:
|
||||
- **Command-based discovery:** If `tools.discoveryCommand` is configured in
|
||||
settings, this command is executed. It's expected to output JSON
|
||||
describing custom tools, which are then registered as `DiscoveredTool`
|
||||
instances.
|
||||
- **MCP-based discovery:** If `mcp.serverCommand` is configured, the
|
||||
registry can connect to a Model Context Protocol (MCP) server to list and
|
||||
register tools (`DiscoveredMCPTool`).
|
||||
- **Providing schemas:** Exposing the `FunctionDeclaration` schemas of all
|
||||
registered tools to the Gemini model, so it knows what tools are available
|
||||
and how to use them.
|
||||
- **Retrieving tools:** Allowing the core to get a specific tool by name for
|
||||
execution.
|
||||
|
||||
## Built-in tools
|
||||
|
||||
The core comes with a suite of pre-defined tools, typically found in
|
||||
`packages/core/src/tools/`. These include:
|
||||
|
||||
- **File system tools:**
|
||||
- `LSTool` (`ls.ts`): Lists directory contents.
|
||||
- `ReadFileTool` (`read-file.ts`): Reads the content of a single file.
|
||||
- `WriteFileTool` (`write-file.ts`): Writes content to a file.
|
||||
- `GrepTool` (`grep.ts`): Searches for patterns in files.
|
||||
- `GlobTool` (`glob.ts`): Finds files matching glob patterns.
|
||||
- `EditTool` (`edit.ts`): Performs in-place modifications to files (often
|
||||
requiring confirmation).
|
||||
- `ReadManyFilesTool` (`read-many-files.ts`): Reads and concatenates content
|
||||
from multiple files or glob patterns (used by the `@` command in CLI).
|
||||
- **Execution tools:**
|
||||
- `ShellTool` (`shell.ts`): Executes arbitrary shell commands (requires
|
||||
careful sandboxing and user confirmation).
|
||||
- **Web tools:**
|
||||
- `WebFetchTool` (`web-fetch.ts`): Fetches content from a URL.
|
||||
- `WebSearchTool` (`web-search.ts`): Performs a web search.
|
||||
- **Memory tools:**
|
||||
- `MemoryTool` (`memoryTool.ts`): Interacts with the AI's memory.
|
||||
|
||||
Each of these tools extends `BaseTool` and implements the required methods for
|
||||
its specific functionality.
|
||||
|
||||
## Tool execution flow
|
||||
|
||||
1. **Model request:** The Gemini model, based on the user's prompt and the
|
||||
provided tool schemas, decides to use a tool and returns a `FunctionCall`
|
||||
part in its response, specifying the tool name and arguments.
|
||||
2. **Core receives request:** The core parses this `FunctionCall`.
|
||||
3. **Tool retrieval:** It looks up the requested tool in the `ToolRegistry`.
|
||||
4. **Parameter validation:** The tool's `validateToolParams()` method is
|
||||
called.
|
||||
5. **Confirmation (if needed):**
|
||||
- The tool's `shouldConfirmExecute()` method is called.
|
||||
- If it returns details for confirmation, the core communicates this back to
|
||||
the CLI, which prompts the user.
|
||||
- The user's decision (e.g., proceed, cancel) is sent back to the core.
|
||||
6. **Execution:** If validated and confirmed (or if no confirmation is needed),
|
||||
the core calls the tool's `execute()` method with the provided arguments and
|
||||
an `AbortSignal` (for potential cancellation).
|
||||
7. **Result processing:** The `ToolResult` from `execute()` is received by the
|
||||
core.
|
||||
8. **Response to model:** The `llmContent` from the `ToolResult` is packaged as
|
||||
a `FunctionResponse` and sent back to the Gemini model so it can continue
|
||||
generating a user-facing response.
|
||||
9. **Display to user:** The `returnDisplay` from the `ToolResult` is sent to
|
||||
the CLI to show the user what the tool did.
|
||||
|
||||
## Extending with custom tools
|
||||
|
||||
While direct programmatic registration of new tools by users isn't explicitly
|
||||
detailed as a primary workflow in the provided files for typical end-users, the
|
||||
architecture supports extension through:
|
||||
|
||||
- **Command-based discovery:** Advanced users or project administrators can
|
||||
define a `tools.discoveryCommand` in `settings.json`. This command, when run
|
||||
by the Gemini CLI core, should output a JSON array of `FunctionDeclaration`
|
||||
objects. The core will then make these available as `DiscoveredTool`
|
||||
instances. The corresponding `tools.callCommand` would then be responsible for
|
||||
actually executing these custom tools.
|
||||
- **MCP server(s):** For more complex scenarios, one or more MCP servers can be
|
||||
set up and configured via the `mcpServers` setting in `settings.json`. The
|
||||
Gemini CLI core can then discover and use tools exposed by these servers. As
|
||||
mentioned, if you have multiple MCP servers, the tool names will be prefixed
|
||||
with the server name from your configuration (e.g.,
|
||||
`serverAlias__actualToolName`).
|
||||
|
||||
This tool system provides a flexible and powerful way to augment the Gemini
|
||||
model's capabilities, making the Gemini CLI a versatile assistant for a wide
|
||||
range of tasks.
|
||||
Reference in New Issue
Block a user