wehub/google-gemini--gemini-cli
1
0
Fork 0
Code Issues Pull Requests Actions 6 Deployments Models Agent Notes Packages Projects Releases Wiki Activity

chore: import upstream snapshot with attribution

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 11:58:09 +08:00
commit c48e26cdd0
2909 changed files with 1591131 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/tools/activate-skill.md
+43
View File
@@ -0,0 +1,43 @@
# Activate skill tool (`activate_skill`)
The `activate_skill` tool lets Gemini CLI load specialized procedural expertise
and resources when they are relevant to your request.
## Description
Skills are packages of instructions and tools designed for specific engineering
tasks, such as reviewing code or creating pull requests. Gemini CLI uses this
tool to "activate" a skill, which provides it with detailed guidelines and
specialized tools tailored to that task.
### Arguments
`activate_skill` takes one argument:
- `name` (enum, required): The name of the skill to activate (for example,
`code-reviewer`, `pr-creator`, or `docs-writer`).
## Usage
The `activate_skill` tool is used exclusively by the Gemini agent. You cannot
invoke this tool manually.
When the agent identifies that a task matches a discovered skill, it requests to
activate that skill. Once activated, the agent's behavior is guided by the
skill's specific instructions until the task is complete.
## Behavior
The agent uses this tool to provide professional-grade assistance:
- **Specialized logic:** Skills contain expert-level procedures for complex
workflows.
- **Dynamic capability:** Activating a skill can grant the agent access to new,
task-specific tools.
- **Contextual awareness:** Skills help the agent focus on the most relevant
standards and conventions for a particular task.
## Next steps
- Learn how to [Use Agent Skills](../cli/skills.md).
- See the [Build agent skills](../cli/creating-skills.md) guide.
docs/tools/ask-user.md
+98
View File
@@ -0,0 +1,98 @@
# Ask User Tool
The `ask_user` tool lets Gemini CLI ask you one or more questions to gather
preferences, clarify requirements, or make decisions. It supports multiple
question types including multiple-choice, free-form text, and Yes/No
confirmation.
## `ask_user` (Ask User)
- **Tool name:** `ask_user`
- **Display name:** Ask User
- **File:** `ask-user.ts`
- **Parameters:**
- `questions` (array of objects, required): A list of 1 to 4 questions to ask.
Each question object has the following properties:
- `question` (string, required): The complete question text.
- `header` (string, required): A short label (max 16 chars) displayed as a
chip/tag (for example, "Auth", "Database").
- `type` (string, optional): The type of question. Defaults to `'choice'`.
- `'choice'`: Multiple-choice with options (supports multi-select).
- `'text'`: Free-form text input.
- `'yesno'`: Yes/No confirmation.
- `options` (array of objects, optional): Required for `'choice'` type. 2-4
selectable options.
- `label` (string, required): Display text (1-5 words).
- `description` (string, required): Brief explanation.
- `multiSelect` (boolean, optional): For `'choice'` type, allows selecting
multiple options. Automatically adds an "All the above" option if there
are multiple standard options.
- `placeholder` (string, optional): Hint text for input fields.
- **Behavior:**
- Presents an interactive dialog to the user with the specified questions.
- Pauses execution until the user provides answers or dismisses the dialog.
- Returns the user's answers to the model.
- **Output (`llmContent`):** A JSON string containing the user's answers,
indexed by question position (for example,
`{"answers":{"0": "Option A", "1": "Some text"}}`).
- **Confirmation:** Yes. The tool inherently involves user interaction.
## Usage Examples
### Multiple Choice Question
```json
{
"questions": [
{
"header": "Database",
"question": "Which database would you like to use?",
"type": "choice",
"options": [
{
"label": "PostgreSQL",
"description": "Powerful, open source object-relational database system."
},
{
"label": "SQLite",
"description": "C-library that implements a SQL database engine."
}
]
}
]
}
```
### Text Input Question
```json
{
"questions": [
{
"header": "Project Name",
"question": "What is the name of your new project?",
"type": "text",
"placeholder": "for example, my-awesome-app"
}
]
}
```
### Yes/No Question
```json
{
"questions": [
{
"header": "Deploy",
"question": "Do you want to deploy the application now?",
"type": "yesno"
}
]
}
```
docs/tools/file-system.md
+129
View File
@@ -0,0 +1,129 @@
# File system tools reference
Gemini CLI core provides a suite of tools for interacting with the local file
system. These tools allow the model to explore and modify your codebase.
## Technical reference
All file system tools operate within a `rootDirectory` (the current working
directory or workspace root) for security.
### `list_directory` (ReadFolder)
Lists the names of files and subdirectories directly within a specified path.
- **Tool name:** `list_directory`
- **Arguments:**
- `dir_path` (string, required): Absolute or relative path to the directory.
- `ignore` (array, optional): Glob patterns to exclude.
- `file_filtering_options` (object, optional): Configuration for `.gitignore`
and `.geminiignore` compliance.
### `read_file` (ReadFile)
Reads and returns the content of a specific file. Supports text, images, audio,
and PDF.
- **Tool name:** `read_file`
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `offset` (number, optional): Start line for text files (0-based).
- `limit` (number, optional): Maximum lines to read.
### `write_file` (WriteFile)
Writes content to a specified file, overwriting it if it exists or creating it
if not.
- **Tool name:** `write_file`
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `content` (string, required): Data to write.
- **Confirmation:** Requires manual user approval.
### `glob` (FindFiles)
Finds files matching specific glob patterns across the workspace.
- **Tool name:** `glob`
- **Display name:** FindFiles
- **File:** `glob.ts`
- **Parameters:**
- `pattern` (string, required): The glob pattern to match against (for
example, `"*.py"`, `"src/**/*.js"`).
- `path` (string, optional): The absolute path to the directory to search
within. If omitted, searches the tool's root directory.
- `case_sensitive` (boolean, optional): Whether the search should be
case-sensitive. Defaults to `false`.
- `respect_git_ignore` (boolean, optional): Whether to respect .gitignore
patterns when finding files. Defaults to `true`.
- **Behavior:**
- Searches for files matching the glob pattern within the specified directory.
- Returns a list of absolute paths, sorted with the most recently modified
files first.
- Ignores common nuisance directories like `node_modules` and `.git` by
default.
- **Output (`llmContent`):** A message like:
`Found 5 file(s) matching "*.ts" within src, sorted by modification time (newest first):\nsrc/file1.ts\nsrc/subdir/file2.ts...`
- **Confirmation:** No.
### `grep_search` (SearchText)
`grep_search` searches for a regular expression pattern within the content of
files in a specified directory. Can filter files by a glob pattern. Returns the
lines containing matches, along with their file paths and line numbers.
- **Tool name:** `grep_search`
- **Display name:** SearchText
- **File:** `grep.ts`
- **Parameters:**
- `pattern` (string, required): The regular expression (regex) to search for
(for example, `"function\s+myFunction"`).
- `path` (string, optional): The absolute path to the directory to search
within. Defaults to the current working directory.
- `include` (string, optional): A glob pattern to filter which files are
searched (for example, `"*.js"`, `"src/**/*.{ts,tsx}"`). If omitted,
searches most files (respecting common ignores).
- **Behavior:**
- Uses `git grep` if available in a Git repository for speed; otherwise, falls
back to system `grep` or a JavaScript-based search.
- Returns a list of matching lines, each prefixed with its file path (relative
to the search directory) and line number.
- **Output (`llmContent`):** A formatted string of matches, for example:
```
Found 3 matches for pattern "myFunction" in path "." (filter: "*.ts"):
---
File: src/utils.ts
L15: export function myFunction() {
L22: myFunction.call();
---
File: src/index.ts
L5: import { myFunction } from './utils';
---
```
- **Confirmation:** No.
### `replace` (Edit)
`replace` replaces text within a file. By default, the tool expects to find and
replace exactly ONE occurrence of `old_string`. If you want to replace multiple
occurrences of the exact same string, set `allow_multiple` to `true`. This tool
is designed for precise, targeted changes and requires significant context
around the `old_string` to ensure it modifies the correct location.
- **Tool name:** `replace`
- **Arguments:**
- `file_path` (string, required): Path to the file.
- `instruction` (string, required): Semantic description of the change.
- `old_string` (string, required): Exact literal text to find.
- `new_string` (string, required): Exact literal text to replace with.
- `allow_multiple` (boolean, optional): If `true`, replaces all occurrences.
If `false` (default), only succeeds if exactly one occurrence is found.
- **Confirmation:** Requires manual user approval.
## Next steps
- Follow the [File management tutorial](../cli/tutorials/file-management.md) for
practical examples.
- Learn about [Trusted folders](../cli/trusted-folders.md) to manage access
permissions.
docs/tools/internal-docs.md
+46
View File
@@ -0,0 +1,46 @@
# Internal documentation tool (`get_internal_docs`)
The `get_internal_docs` tool lets Gemini CLI access its own technical
documentation to provide more accurate answers about its capabilities and usage.
## Description
This tool is used when Gemini CLI needs to verify specific details about Gemini
CLI's internal features, built-in commands, or configuration options. It
provides direct access to the Markdown files in the `docs/` directory.
### Arguments
`get_internal_docs` takes one optional argument:
- `path` (string, optional): The relative path to a specific documentation file
(for example, `reference/commands.md`). If omitted, the tool returns a list of
all available documentation paths.
## Usage
The `get_internal_docs` tool is used exclusively by Gemini CLI. You cannot
invoke this tool manually.
When Gemini CLI uses this tool, it retrieves the content of the requested
documentation file and processes it to answer your question. This ensures that
the information provided by the AI is grounded in the latest project
documentation.
## Behavior
Gemini CLI uses this tool to ensure technical accuracy:
- **Capability discovery:** If Gemini CLI is unsure how a feature works, it can
lookup the corresponding documentation.
- **Reference lookup:** Gemini CLI can verify slash command sub-commands or
specific setting names.
- **Self-correction:** Gemini CLI can use the documentation to correct its
understanding of Gemini CLI's system logic.
## Next steps
- Explore the [Command reference](../reference/commands.md) for a detailed guide
to slash commands.
- See the [Configuration guide](../reference/configuration.md) for settings
reference.
docs/tools/mcp-resources.md
+44
View File
@@ -0,0 +1,44 @@
# MCP resource tools
MCP resource tools let Gemini CLI discover and retrieve data from contextual
resources exposed by Model Context Protocol (MCP) servers.
## 1. `list_mcp_resources` (ListMcpResources)
`list_mcp_resources` retrieves a list of all available resources from connected
MCP servers. This is primarily a discovery tool that helps the model understand
what external data sources are available for reference.
- **Tool name:** `list_mcp_resources`
- **Display name:** List MCP Resources
- **Kind:** `Search`
- **File:** `list-mcp-resources.ts`
- **Parameters:**
- `serverName` (string, optional): An optional filter to list resources from a
specific server.
- **Behavior:**
- Iterates through all connected MCP servers.
- Fetches the list of resources each server exposes.
- Formats the results into a plain-text list of URIs and descriptions.
- **Output (`llmContent`):** A formatted list of available resources, including
their URI, server name, and optional description.
- **Confirmation:** No. This is a read-only discovery tool.
## 2. `read_mcp_resource` (ReadMcpResource)
`read_mcp_resource` retrieves the content of a specific resource identified by
its URI.
- **Tool name:** `read_mcp_resource`
- **Display name:** Read MCP Resource
- **Kind:** `Read`
- **File:** `read-mcp-resource.ts`
- **Parameters:**
- `uri` (string, required): The URI of the MCP resource to read.
- **Behavior:**
- Locates the resource and its associated server by URI.
- Calls the server's `resources/read` method.
- Processes the response, extracting text or binary data.
- **Output (`llmContent`):** The content of the resource. For binary data, it
returns a placeholder indicating the data type.
- **Confirmation:** No. This is a read-only retrieval tool.
docs/tools/mcp-server.md
+1233
View File
File diff suppressed because it is too large Load Diff
docs/tools/memory.md
+32
View File
@@ -0,0 +1,32 @@
# Memory files
Gemini CLI persists durable facts, user preferences, and project details by
editing Markdown memory files directly.
## Technical reference
The agent routes memories to the appropriate Markdown file: shared project
instructions go in repository `GEMINI.md` files, private project notes go in the
per-project private memory folder, and cross-project personal preferences go in
the global `~/.gemini/GEMINI.md` file.
## Technical behavior
- **Storage:** Edits Markdown files with `write_file` or `replace`.
- **Loading:** The stored facts are automatically included in the hierarchical
context system for all future sessions.
- **Format:** Keeps durable instructions concise and avoids duplicating the same
fact across multiple memory tiers.
## Use cases
- Persisting user preferences (for example, "I prefer functional programming").
- Saving project-wide architectural decisions.
- Storing frequently used aliases or system configurations.
## Next steps
- Follow the [Memory management guide](../cli/tutorials/memory-management.md)
for practical examples.
- Learn how the [Project context (GEMINI.md)](../cli/gemini-md.md) system loads
this information.
docs/tools/planning.md
+62
View File
@@ -0,0 +1,62 @@
# Gemini CLI planning tools
Planning tools let Gemini CLI switch into a safe, read-only "Plan Mode" for
researching and planning complex changes, and to signal the finalization of a
plan to the user.
## 1. `enter_plan_mode` (EnterPlanMode)
`enter_plan_mode` switches the CLI to Plan Mode. This tool is typically called
by the agent when you ask it to "start a plan" using natural language. In this
mode, the agent is restricted to read-only tools to allow for safe exploration
and planning.
<!-- prettier-ignore -->
> [!NOTE]
> This tool is not available when the CLI is in YOLO mode.
- **Tool name:** `enter_plan_mode`
- **Display name:** Enter Plan Mode
- **File:** `enter-plan-mode.ts`
- **Parameters:**
- `reason` (string, optional): A short reason explaining why the agent is
entering plan mode (for example, "Starting a complex feature
implementation").
- **Behavior:**
- Switches the CLI's approval mode to `PLAN`.
- Notifies the user that the agent has entered Plan Mode.
- **Output (`llmContent`):** A message indicating the switch, for example,
`Switching to Plan mode.`
- **Confirmation:** Yes. The user is prompted to confirm entering Plan Mode.
## 2. `exit_plan_mode` (ExitPlanMode)
`exit_plan_mode` signals that the planning phase is complete. It presents the
finalized plan to the user and requests formal approval to start the
implementation. The agent MUST reach an informal agreement with the user in the
chat regarding the proposed strategy BEFORE calling this tool.
- **Tool name:** `exit_plan_mode`
- **Display name:** Exit Plan Mode
- **File:** `exit-plan-mode.ts`
- **Parameters:**
- `plan_path` (string, required): The path to the finalized Markdown plan
file. This file MUST be located within the project's temporary plans
directory (for example, `~/.gemini/tmp/<project>/plans/`).
- **Behavior:**
- Validates that the `plan_path` is within the allowed directory and that the
file exists and has content.
- Presents the plan to the user for formal review.
- If the user approves the plan:
- Switches the CLI's approval mode to the user's chosen approval mode (
`DEFAULT` or `AUTO_EDIT`).
- Marks the plan as approved for implementation.
- If the user rejects the plan:
- Stays in Plan Mode.
- Returns user feedback to the model to refine the plan.
- **Output (`llmContent`):**
- On approval: A message indicating the plan was approved and the new approval
mode.
- On rejection: A message containing the user's feedback.
- **Confirmation:** Yes. Shows the finalized plan and asks for user formal
approval to proceed with implementation.
docs/tools/shell.md
+241
View File
@@ -0,0 +1,241 @@
# Shell tool (`run_shell_command`)
The `run_shell_command` tool allows the Gemini model to execute commands
directly on your system's shell. It is the primary mechanism for the agent to
interact with your environment beyond simple file edits.
## Technical reference
On Windows, commands execute with `powershell.exe -NoProfile -Command`. On other
platforms, they execute with `bash -c`.
### Arguments
- `command` (string, required): The exact shell command to execute.
- `description` (string, optional): A brief description shown to the user for
confirmation.
- `dir_path` (string, optional): The absolute path or relative path from
workspace root where the command runs.
- `is_background` (boolean, optional): Whether to move the process to the
background immediately after starting.
### Policy engine shorthands
The [policy engine](../reference/policy-engine.md) provides two convenience
fields for writing rules that target shell commands:
- `commandPrefix`: Matches if the `command` argument starts with a given string.
- `commandRegex`: Matches if the `command` argument matches a given regular
expression.
These are syntactic sugar for combining `toolName = "run_shell_command"` with an
`argsPattern` in a policy TOML file. They are **not** arguments of
`run_shell_command` itself.
For details on writing shell-specific policy rules, see
[Special syntax for `run_shell_command`](../reference/policy-engine.md#special-syntax-for-run_shell_command)
in the policy engine reference.
### Return values
The tool returns a JSON object containing:
- `Command`: The executed string.
- `Directory`: The execution path.
- `Stdout` / `Stderr`: The output streams.
- `Exit Code`: The process return code.
- `Background PIDs`: PIDs of any started background processes.
## Configuration
You can configure the behavior of the `run_shell_command` tool by modifying your
`settings.json` file or by using the `/settings` command in Gemini CLI.
### Enabling interactive commands
To enable interactive commands, you need to set the
`tools.shell.enableInteractiveShell` setting to `true`. This will use `node-pty`
for shell command execution, which allows for interactive sessions. If
`node-pty` is not available, it will fall back to the `child_process`
implementation, which does not support interactive commands.
**Example `settings.json`:**
```json
{
"tools": {
"shell": {
"enableInteractiveShell": true
}
}
}
```
### Showing color in output
To show color in the shell output, you need to set the `tools.shell.showColor`
setting to `true`. This setting only applies when
`tools.shell.enableInteractiveShell` is enabled.
**Example `settings.json`:**
```json
{
"tools": {
"shell": {
"showColor": true
}
}
}
```
### Setting the pager
You can set a custom pager for the shell output by setting the
`tools.shell.pager` setting. The default pager is `cat`. This setting only
applies when `tools.shell.enableInteractiveShell` is enabled.
**Example `settings.json`:**
```json
{
"tools": {
"shell": {
"pager": "less"
}
}
}
```
## Interactive commands
The `run_shell_command` tool now supports interactive commands by integrating a
pseudo-terminal (pty). This lets you run commands that require real-time user
input, such as text editors (`vim`, `nano`), terminal-based UIs (`htop`), and
interactive version control operations (`git rebase -i`).
When an interactive command is running, you can send input to it from the Gemini
CLI. To focus on the interactive shell, press `Tab`. The terminal output,
including complex TUIs, will be rendered correctly.
## Important notes
- **Security:** Be cautious when executing commands, especially those
constructed from user input, to prevent security vulnerabilities.
- **Error handling:** Check the `Stderr`, `Error`, and `Exit Code` fields to
determine if a command executed successfully.
- **Background processes:** When a command is run in the background with `&`,
the tool will return immediately and the process will continue to run in the
background. The `Background PIDs` field will contain the process ID of the
background process.
## Environment variables
When `run_shell_command` executes a command, it sets the `GEMINI_CLI=1`
environment variable in the subprocess's environment. This allows scripts or
tools to detect if they are being run from within Gemini CLI.
## Command restrictions
<!-- prettier-ignore -->
> [!WARNING]
> The `tools.core` setting is an **allowlist for _all_ built-in
> tools**, not just shell commands. When you set `tools.core` to any value,
> _only_ the tools explicitly listed will be enabled. This includes all built-in
> tools like `read_file`, `write_file`, `glob`, `grep_search`, `list_directory`,
> `replace`, etc.
You can restrict the commands that can be executed by the `run_shell_command`
tool by using the `tools.core` and `tools.exclude` settings in your
configuration file.
- `tools.core`: To restrict `run_shell_command` to a specific set of commands,
add entries to the `core` list under the `tools` category in the format
`run_shell_command(<command>)`. For example,
`"tools": {"core": ["run_shell_command(git)"]}` will only allow `git`
commands. Including the generic `run_shell_command` acts as a wildcard,
allowing any command not explicitly blocked.
- `tools.exclude` [DEPRECATED]: To block specific commands, use the
[Policy Engine](../reference/policy-engine.md). Historically, this setting
allowed adding entries to the `exclude` list under the `tools` category in the
format `run_shell_command(<command>)`. For example,
`"tools": {"exclude": ["run_shell_command(rm)"]}` will block `rm` commands.
The validation logic is designed to be secure and flexible:
1. **Command chaining disabled**: The tool automatically splits commands
chained with `&&`, `||`, or `;` and validates each part separately. If any
part of the chain is disallowed, the entire command is blocked.
2. **Prefix matching**: The tool uses prefix matching. For example, if you
allow `git`, you can run `git status` or `git log`.
3. **Blocklist precedence**: The `tools.exclude` list is always checked first.
If a command matches a blocked prefix, it will be denied, even if it also
matches an allowed prefix in `tools.core`.
### Command restriction examples
**Allow only specific command prefixes**
To allow only `git` and `npm` commands, and block all others:
```json
{
"tools": {
"core": ["run_shell_command(git)", "run_shell_command(npm)"]
}
}
```
- `git status`: Allowed
- `npm install`: Allowed
- `ls -l`: Blocked
**Block specific command prefixes**
To block `rm` and allow all other commands:
```json
{
"tools": {
"core": ["run_shell_command"],
"exclude": ["run_shell_command(rm)"]
}
}
```
- `rm -rf /`: Blocked
- `git status`: Allowed
- `npm install`: Allowed
**Blocklist takes precedence**
If a command prefix is in both `tools.core` and `tools.exclude`, it will be
blocked.
- **`tools.shell.enableInteractiveShell`**: (boolean) Uses `node-pty` for
real-time interaction.
- **`tools.shell.showColor`**: (boolean) Preserves ANSI colors in output.
- **`tools.shell.inactivityTimeout`**: (number) Seconds to wait for output
before killing the process.
### Command restrictions
You can limit which commands the agent is allowed to request using these
settings:
- **`tools.core`**: An allowlist of command prefixes (for example,
`["git", "npm test"]`).
- **`tools.exclude`**: A blocklist of command prefixes.
## Use cases
- Running build scripts and test suites.
- Initializing or managing version control systems.
- Installing project dependencies.
- Starting development servers or background watchers.
## Next steps
- Follow the [Shell commands tutorial](../cli/tutorials/shell-commands.md) for
practical examples.
- Learn about [Sandboxing](../cli/sandbox.md) to isolate command execution.
docs/tools/todos.md
+36
View File
@@ -0,0 +1,36 @@
# Todo tool (`write_todos`)
The `write_todos` tool allows the Gemini agent to maintain an internal list of
subtasks for multi-step requests.
## Technical reference
The agent uses this tool to manage its execution plan and provide progress
updates to the CLI interface.
### Arguments
- `todos` (array of objects, required): The complete list of tasks. Each object
includes:
- `description` (string): Technical description of the task.
- `status` (enum): `pending`, `in_progress`, `completed`, `cancelled`, or
`blocked`.
## Technical behavior
- **Interface:** Updates the progress indicator above the CLI input prompt.
- **Exclusivity:** Only one task can be marked `in_progress` at any time.
- **Persistence:** Todo state is scoped to the current session.
- **Interaction:** Users can toggle the full list view using **Ctrl+T**.
## Use cases
- Breaking down a complex feature implementation into manageable steps.
- Coordinating multi-file refactoring tasks.
- Providing visibility into the agent's current focus during long-running tasks.
## Next steps
- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
usage details.
- Learn about [Session management](../cli/session-management.md) for context.
docs/tools/tracker.md
+61
View File
@@ -0,0 +1,61 @@
# Tracker tools (`tracker_*`)
<!-- prettier-ignore -->
> [!NOTE]
> This is an experimental feature currently under active development.
The `tracker_*` tools allow the Gemini agent to maintain an internal, persistent
graph of tasks and dependencies for multi-step requests. This suite of tools
provides a more robust and granular way to manage execution plans than the
legacy `write_todos` tool.
## Technical reference
The agent uses these tools to manage its execution plan, decompose complex goals
into actionable sub-tasks, and provide real-time progress updates to the CLI
interface. The task state is stored in the `.gemini/tmp/tracker/<session-id>`
directory, allowing the agent to manage its plan for the current session.
### Available Tools
- `tracker_create_task`: Creates a new task in the tracker. You can specify a
title, description, and task type (`epic`, `task`, `bug`).
- `tracker_update_task`: Updates an existing task's status (`open`,
`in_progress`, `blocked`, `closed`), description, or dependencies.
- `tracker_get_task`: Retrieves the full details of a specific task by its
6-character hex ID.
- `tracker_list_tasks`: Lists tasks in the tracker, optionally filtered by
status, type, or parent ID.
- `tracker_add_dependency`: Adds a dependency between two tasks, ensuring
topological execution.
- `tracker_visualize`: Renders an ASCII tree visualization of the current task
graph.
## Technical behavior
- **Interface:** Updates the progress indicator and task tree above the CLI
input prompt.
- **Persistence:** Task state is saved automatically to the
`.gemini/tmp/tracker/<session-id>` directory. Task states are session-specific
and do not persist across different sessions.
- **Dependencies:** Tasks can depend on other tasks, forming a directed acyclic
graph (DAG). The agent must resolve dependencies before starting blocked
tasks.
- **Interaction:** Users can view the current state of the tracker by asking the
agent to visualize it, or by running `gemini-cli` commands if implemented.
## Use cases
- Coordinating multi-file refactoring projects.
- Breaking down a mission into a hierarchy of epics and tasks for better
visibility.
- Tracking bugs and feature requests directly within the context of an active
codebase.
- Providing visibility into the agent's current focus and remaining work.
## Next steps
- Follow the [Task planning tutorial](../cli/tutorials/task-planning.md) for
usage details and migration from the legacy todo list.
- Learn about [Session management](../cli/session-management.md) for context on
persistent state.
docs/tools/web-fetch.md
+38
View File
@@ -0,0 +1,38 @@
# Web fetch tool (`web_fetch`)
The `web_fetch` tool allows the Gemini agent to retrieve and process content
from specific URLs provided in your prompt.
## Technical reference
The agent uses this tool when you include URLs in your prompt and request
specific operations like summarization or extraction.
### Arguments
- `prompt` (string, required): A request containing up to 20 valid URLs
(starting with `http://` or `https://`) and instructions on how to process
them.
## Technical behavior
- **Confirmation:** Triggers a confirmation dialog showing the converted URLs.
- **Plan Mode:** In [Plan Mode](../cli/plan-mode.md), `web_fetch` is available
but always requires explicit user confirmation (`ask_user`) due to security
implications of accessing external or private network addresses.
- **Processing:** Uses the Gemini API's `urlContext` for retrieval.
- **Fallback:** If API access fails, the tool attempts to fetch raw content
directly from your local machine.
- **Formatting:** Returns a synthesized response with source attribution.
## Use cases
- Summarizing technical articles or blog posts.
- Comparing data between two or more web pages.
- Extracting specific information from a documentation site.
## Next steps
- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
usage examples.
- See the [Web search tool reference](./web-search.md) for general queries.
docs/tools/web-search.md
+32
View File
@@ -0,0 +1,32 @@
# Web search tool (`google_web_search`)
The `google_web_search` tool allows the Gemini agent to retrieve up-to-date
information, news, and facts from the internet via Google Search.
## Technical reference
The agent uses this tool when your request requires knowledge of current events
or specific online documentation not available in its internal training data.
### Arguments
- `query` (string, required): The search query to be executed.
## Technical behavior
- **Grounding:** Returns a generated summary based on search results.
- **Citations:** Includes source URIs and titles for factual grounding.
- **Processing:** The Gemini API processes the search results before returning a
synthesized response to the agent.
## Use cases
- Researching the latest version of a software library or API.
- Finding solutions to recent software bugs or security vulnerabilities.
- Retrieving news or documentation updated after the model's knowledge cutoff.
## Next steps
- Follow the [Web tools guide](../cli/tutorials/web-tools.md) for practical
usage examples.
- Explore the [Web fetch tool reference](./web-fetch.md) for direct URL access.