MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-05-15 06:12:50 -07:00
Code Issues Packages Projects Releases Wiki Activity

docs: weekly audit results for 24319780415

Browse Source
This commit is contained in:
github-merge-queue
2026-04-13 00:17:35 +00:00
committed by github-actions[bot]
parent 0179726222
commit 3266d7dbd8
15 changed files with 187 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+3 -4
View File
@@ -1,7 +1,8 @@
# How to contribute
We would love to accept your patches and contributions to this project. This
document includes:
Gemini CLI welcomes patches and contributions from the community. This document
outlines the process for becoming a contributor and setting up your development
environment.
- **[Before you begin](#before-you-begin):** Essential steps to take before
becoming a Gemini CLI contributor.
@@ -12,8 +13,6 @@ document includes:
- **[Documentation contribution process](#documentation-contribution-process):**
How to contribute documentation to Gemini CLI.
We're looking forward to seeing your contributions!
## Before you begin
### Sign our Contributor License Agreement
audit-implementation-log-2026-04-13.md
+32
View File
@@ -0,0 +1,32 @@
# Documentation Audit Implementation Log - 2026-04-13
## Summary
Implementation of recommendations from the 2026-04-13 audit.
## Manual Changes
| File Path | Change Description | Reasoning | Status |
| ------------------------------------- | ----------------------------------------- | ------------------------------------- | --------- |
| `docs/index.md` | Fixed contributing link. | Adherence to relative link guideline. | Completed |
| `docs/get-started/index.md` | Rephrased intro and fixed prompt names. | Conciseness and branding consistency. | Completed |
| `docs/cli/cli-reference.md` | Fixed punctuation. | Grammar correctness. | Completed |
| `docs/releases.md` | Fixed casing, links, and passive voice. | Style guide adherence. | Completed |
| `docs/cli/plan-mode.md` | Bolded UI mode names. | Style guide adherence. | Completed |
| `docs/local-development.md` | Replaced "allows you to" with "lets you". | Style guide adherence. | Completed |
| `docs/resources/quota-and-pricing.md` | Fixed passive voice and punctuation. | Style guide adherence. | Completed |
## New Content
| File Path | Description | Reasoning | Status |
| --------------------------------- | ----------------------------------------- | ----------------------------------------- | --------- |
| `docs/cli/notifications.md` | Documented `general.enableNotifications`. | Undocumented feature identified in audit. | Completed |
| `docs/reference/policy-engine.md` | Added Conseca section. | Undocumented feature identified in audit. | Completed |
## Automated Steps
| Task | Command | Status |
| ---------------------- | -------------------------- | ------- |
| Regenerate Settings | `npm run docs:settings` | Pending |
| Regenerate Keybindings | `npm run docs:keybindings` | Pending |
| Format Docset | `npm run format` | Pending |
audit-results-2026-04-13.md
+45
View File
@@ -0,0 +1,45 @@
# Documentation Audit Results - 2026-04-13
## Summary
Audit initiated to ensure documentation correctness and style consistency. All
69 documentation files identified in `sidebar.json` were considered.
## Phase 1: Editor Audit Findings
| File Path | Violation Description | Recommendation |
| ------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- |
| `docs/index.md` | Link Quality: Uses absolute path `/docs/contributing`. | Change to relative path `./contributing.md`. |
| `docs/get-started/index.md` | Voice and Tone: Repetitive use of "Gemini CLI" in a single sentence. | Rephrase to be more concise. |
| `docs/get-started/index.md` | Voice and Tone: Uses "Gemini" instead of "Gemini CLI" in prompt examples. | Replace "Gemini" with "Gemini CLI". |
| `docs/get-started/index.md` | Poor Vocabulary: Uses "You wish to" instead of "You want to". | Replace "wish to" with "want to". |
| `docs/cli/cli-reference.md` | Punctuation: Missing comma after "for example". | Add comma: "(for example, --resume 5)". |
| `docs/releases.md` | Casing: "Github-hosted" should be "GitHub-hosted". | Correct casing. |
| `docs/releases.md` | Link Quality: Uses absolute path `(npm.md)`. | Change to relative path `(./npm.md)`. |
| `docs/releases.md` | Passive Voice: "smoke testing should be performed". | Change to "Perform smoke testing". |
| `docs/releases.md` | Passive Voice: "Smoke testing ... is recommended". | Change to "We recommend performing smoke testing" -> "Perform smoke testing". |
| `docs/cli/plan-mode.md` | Formatting: Mode names (Default, Auto-Edit, Plan) are not bolded. | Bold mode names as UI elements. |
| `docs/local-development.md` | Lack of Conciseness: Uses "allows you to". | Replace with "lets you". |
| `docs/resources/quota-and-pricing.md` | Terminology: Uses "limit on your quota" redundantly. | Streamline phrasing. |
| `docs/resources/quota-and-pricing.md` | Punctuation: Uses curly apostrophe in "It’s". | Replace with straight apostrophe. |
| `docs/resources/quota-and-pricing.md` | Passive Voice: "Requests are limited", "usage is governed", "requests will be made". | Rephrase to active voice. |
| `docs/contributing.md` | Missing Overview: Document lacks a brief overview paragraph. | Add a brief overview. |
## Phase 2: Software Engineer Audit Findings
| Feature/Setting | Description | Documentation Status | Recommendation |
| ----------------------------- | --------------------------------------------- | --------------------- | -------------------------------------------------------- |
| `general.enableNotifications` | Run-event notifications for prompts/sessions. | Undocumented. | Add to `docs/cli/notifications.md`. |
| `ui.escapePastedAtSymbols` | Prevents unintended @path expansion on paste. | Undocumented. | Add to `docs/cli/settings.md`. |
| `ui.compactToolOutput` | Structured display for tool outputs. | Undocumented. | Add to `docs/cli/settings.md`. |
| `security.enableConseca` | Context-Aware Security Checker (LLM-based). | Undocumented. | Create `docs/cli/conseca.md` or add to `security.md`. |
| `experimental.worktrees` | Automated Git worktree management. | Partially documented. | Update `docs/cli/git-worktrees.md` with setting details. |
| `update_topic` Tool | Topic & status reporting for agents. | Partially documented. | Add to `docs/reference/tools.md` with links. |
| `tracker_*` Tools | Task dependency and progress tracking. | Partially documented. | Add to `docs/reference/tools.md` with links. |
| `jitContext` Setting | Just-In-Time context loading. | Undocumented. | Add to `docs/cli/settings.md`. |
## Overall Recommendation
The docset requires a general pass to convert "the Gemini CLI" to "Gemini CLI",
replace "we/they/the user" with "you", and fix passive voice. Automated settings
regeneration should be run after manual edits.
docs/cli/cli-reference.md
+1 -1
View File
@@ -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 (for example `--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/model.md
+2 -2
View File
@@ -27,8 +27,8 @@ Running this command will open a dialog with your options:
| Auto (Gemini 2.5) | Let the system choose the best Gemini 2.5 model for your task. | gemini-2.5-pro, gemini-2.5-flash |
| Manual | Select a specific model. | Any available model. |
We recommend selecting one of the above **Auto** options. However, you can
select **Manual** to select a specific model from those available.
Gemini CLI recommends selecting one of the above **Auto** options. However, you
can select **Manual** to select a specific model from those available.
You can also use the `--model` flag to specify a particular Gemini model on
startup. For more details, refer to the
docs/cli/notifications.md
+31 -45
View File
@@ -1,59 +1,45 @@
# Notifications (experimental)
# Notifications
Gemini CLI can send system notifications to alert you when a session completes
or when it needs your attention, such as when it's waiting for you to approve a
tool call.
Gemini CLI can provide run-event notifications to alert you when an action is
required or when a long-running session completes.
<!-- prettier-ignore -->
> [!NOTE]
> This is an experimental feature currently under active development and
> may need to be enabled under `/settings`.
## Overview
Notifications are particularly useful when running long-running tasks or using
[Plan Mode](./plan-mode.md), letting you switch to other windows while Gemini
CLI works in the background.
Notifications help you stay informed about the agent's progress without
constantly monitoring the terminal. When enabled, Gemini CLI uses system-level
notifications to alert you in the following scenarios:
## Requirements
### Terminal support
The CLI uses the OSC 9 terminal escape sequence to trigger system notifications.
This is supported by several modern terminal emulators including iTerm2,
WezTerm, Ghostty, and Kitty. If your terminal does not support OSC 9
notifications, Gemini CLI falls back to a terminal bell (BEL) to get your
attention. Most terminals respond to BEL with a taskbar flash or system alert
sound.
- **Action required:** When the agent is waiting for your approval to execute a
tool.
- **Session completed:** When a sequence of tasks has finished.
- **Critical errors:** When a session terminates due to an error.
## Enable notifications
Notifications are disabled by default. You can enable them using the `/settings`
command or by updating your `settings.json` file.
To enable notifications, set the `general.enableNotifications` setting to
`true`.
1. Open the settings dialog by typing `/settings` in an interactive session.
2. Navigate to the **General** category.
3. Toggle the **Enable Notifications** setting to **On**.
Alternatively, add the following to your `settings.json`:
```json
{
"general": {
"enableNotifications": true
}
}
```bash
gemini config set general.enableNotifications true
```
## Types of notifications
Alternatively, you can enable them via the `/settings` dialog:
Gemini CLI sends notifications for the following events:
1. Open the settings dialog by typing `/settings`.
2. Navigate to the **General** category.
3. Check the **Enable Notifications** box.
- **Action required:** Triggered when the model is waiting for user input or
tool approval. This helps you know when the CLI has paused and needs you to
intervene.
- **Session complete:** Triggered when a session finishes successfully. This is
useful for tracking the completion of automated tasks.
## Requirements
## Next steps
Notifications depend on your operating system's capabilities:
- Start planning with [Plan Mode](./plan-mode.md).
- Configure your experience with other [settings](./settings.md).
- **macOS:** Uses the built-in Notification Center.
- **Linux:** Requires a notification daemon (like `dunst` or `notify-osd`) and
the `notify-send` utility.
- **Windows:** Uses the Windows Action Center.
<!-- prettier-ignore -->
> [!NOTE]
> In some terminal environments or remote sessions (like SSH), system
> notifications may not be available or may require additional configuration on
> the host machine.
docs/cli/plan-mode.md
+3 -3
View File
@@ -35,9 +35,9 @@ To launch Gemini CLI in Plan Mode once:
To start Plan Mode while using Gemini CLI:
- **Keyboard shortcut:** Press `Shift+Tab` to cycle through approval modes
(`Default` -> `Auto-Edit` -> `Plan`). Plan Mode is automatically removed from
the rotation when Gemini CLI is actively processing or showing confirmation
dialogs.
(**Default** -> **Auto-Edit** -> **Plan**). Plan Mode is automatically removed
from the rotation when Gemini CLI is actively processing or showing
confirmation dialogs.
- **Command:** Type `/plan [goal]` in the input box. The `[goal]` is optional;
for example, `/plan implement authentication` will switch to Plan Mode and
docs/get-started/index.md
+4 -4
View File
@@ -18,7 +18,7 @@ The standard method to install and run Gemini CLI uses `npm`:
npm install -g @google/gemini-cli
```
Once Gemini CLI is installed, run Gemini CLI from your command line:
Once installed, run Gemini CLI from your command line:
```bash
gemini
@@ -87,7 +87,7 @@ Give Gemini the following prompt:
Rename the photos in my "photos" directory based on their contents.
```
Result: Gemini asks for permission to rename your files.
Result: Gemini CLI asks for permission to rename your files.
Select **Allow once** and your files are renamed:
@@ -111,7 +111,7 @@ Give Gemini CLI the following prompt:
Clone the 'chalk' repository from https://github.com/chalk/chalk, read its key source files, and explain how it works.
```
Result: Gemini performs a sequence of actions to answer your request.
Result: Gemini CLI performs a sequence of actions to answer your request.
1. First, it asks for permission to run `git clone` to download the repository.
2. Next, it finds the important source files and asks for permission to read
@@ -178,7 +178,7 @@ Gemini CLI can generate boilerplate code and tests based on your existing
implementation. This example demonstrates how to request code coverage for a
JavaScript component.
Scenario: You've written a simple login page. You wish to write unit tests to
Scenario: You've written a simple login page. You want to write unit tests to
ensure that your login page has code coverage.
Give Gemini CLI the following prompt:
docs/get-started/installation.md
+4 -4
View File
@@ -20,7 +20,7 @@ installation methods, and release types.
## Install Gemini CLI
We recommend most users install Gemini CLI using one of the following
Gemini CLI recommends that most users install it using one of the following
installation methods:
- npm
@@ -63,7 +63,7 @@ npm install -g @google/gemini-cli
## Run Gemini CLI
For most users, we recommend running Gemini CLI with the `gemini` command:
Start Gemini CLI with the `gemini` command:
```bash
gemini
@@ -143,8 +143,8 @@ code.
## Releases
Gemini CLI has three release channels: nightly, preview, and stable. For most
users, we recommend the stable release, which is the default installation.
Gemini CLI has three release channels: nightly, preview, and stable. The stable
release is the default installation and is recommended for most users.
### Stable
docs/index.md
+1 -1
View File
@@ -124,7 +124,7 @@ Support, release history, and legal information.
## Development
- **[Contribution guide](/docs/contributing):** How to contribute to Gemini CLI.
- **[Contribution guide](./contributing.md):** How to contribute to Gemini CLI.
- **[Integration testing](./integration-tests.md):** Running integration tests.
- **[Issue and PR automation](./issue-and-pr-automation.md):** Automation for
issues and pull requests.
docs/local-development.md
+1 -1
View File
@@ -148,7 +148,7 @@ await runInDevTraceSpan(
},
},
async ({ metadata }) => {
// metadata allows you to record the input and output of the
// metadata lets you record the input and output of the
// operation as well as other attributes.
metadata.input = { key: 'value' };
// Set custom attributes.
docs/reference/policy-engine.md
+30
View File
@@ -466,6 +466,36 @@ deny_message = "Deep codebase analysis is restricted for this session."
tool, use the `subagent` field instead. See
[TOML rule schema](#toml-rule-schema).
## Context-Aware Security (Conseca)
Context-Aware Security (Conseca) is an experimental feature that uses an LLM to
dynamically evaluate tool calls based on the intent of your prompt. It provides
an additional layer of protection by identifying potentially harmful actions
that might otherwise match an "allow" rule.
### How it works
When Conseca is enabled, every tool call that would be automatically allowed is
first sent to a security classifier. The classifier analyzes the tool call, its
arguments, and the original user prompt to determine if the action is safe and
aligned with the user's intent.
If the classifier identifies a potential security risk, it can override an
`allow` decision and force it to `ask_user` or `deny`.
### Enable Conseca
To enable Conseca, set the `security.enableConseca` setting to `true`.
```bash
gemini config set security.enableConseca true
```
<!-- prettier-ignore -->
> [!NOTE]
> Conseca is an experimental feature and may increase the latency of tool
> execution, as it requires an additional model call for security validation.
## Default policies
Gemini CLI ships with a set of default policies to provide a safe out-of-the-box
docs/reference/tools.md
+9 -9
View File
@@ -115,15 +115,15 @@ each tool.
### Task Tracking
| Tool | Kind | Description |
| :----------------------- | :------ | :-------------------------------------------------------------------------- |
| `tracker_add_dependency` | `Think` | Adds a dependency between two existing tasks in the tracker. |
| `tracker_create_task` | `Think` | Creates a new task in the internal tracker to monitor progress. |
| `tracker_get_task` | `Think` | Retrieves the details and current status of a specific tracked task. |
| `tracker_list_tasks` | `Think` | Lists all tasks currently being tracked. |
| `tracker_update_task` | `Think` | Updates the status or details of an existing task. |
| `tracker_visualize` | `Think` | Generates a visual representation of the current task dependency graph. |
| `update_topic` | `Think` | Updates the current topic and status to keep the user informed of progress. |
| Tool | Kind | Description |
| :----------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------- |
| [`tracker_add_dependency`](../cli/tutorials/automation.md#task-tracking) | `Think` | Adds a dependency between two existing tasks in the tracker. |
| [`tracker_create_task`](../cli/tutorials/automation.md#task-tracking) | `Think` | Creates a new task in the internal tracker to monitor progress. |
| [`tracker_get_task`](../cli/tutorials/automation.md#task-tracking) | `Think` | Retrieves the details and current status of a specific tracked task. |
| [`tracker_list_tasks`](../cli/tutorials/automation.md#task-tracking) | `Think` | Lists all tasks currently being tracked. |
| [`tracker_update_task`](../cli/tutorials/automation.md#task-tracking) | `Think` | Updates the status or details of an existing task. |
| [`tracker_visualize`](../cli/tutorials/automation.md#task-tracking) | `Think` | Generates a visual representation of the current task dependency graph. |
| [`update_topic`](../cli/tutorials/automation.md#status-reporting) | `Think` | Updates the current topic and status to keep the user informed of progress. |
### Web
docs/releases.md
+12 -13
View File
@@ -8,7 +8,7 @@
Our release flows support both `dev` and `prod` environments.
The `dev` environment pushes to a private Github-hosted NPM repository, with the
The `dev` environment pushes to a private GitHub-hosted NPM repository, with the
package names beginning with `@google-gemini/**` instead of `@google/**`.
The `prod` environment pushes to the public global NPM registry via Wombat
@@ -16,11 +16,11 @@ Dressing Room, which is Google's system for managing NPM packages in the
`@google/**` namespace. The packages are all named `@google/**`.
More information can be found about these systems in the
[NPM Package Overview](npm.md)
[NPM package structure](./npm.md)
### Package scopes
| Package | `prod` (Wombat Dressing Room) | `dev` (Github Private NPM Repo) |
| Package | `prod` (Wombat Dressing Room) | `dev` (GitHub Private NPM Repo) |
| ---------- | ----------------------------- | ----------------------------------------- |
| CLI | @google/gemini-cli | @google-gemini/gemini-cli |
| Core | @google/gemini-cli-core | @google-gemini/gemini-cli-core A2A Server |
@@ -28,10 +28,10 @@ More information can be found about these systems in the
## Release cadence and tags
We will follow https://semver.org/ as closely as possible but will call out when
or if we have to deviate from it. Our weekly releases will be minor version
increments and any bug or hotfixes between releases will go out as patch
versions on the most recent release.
We follow [Semantic Versioning](https://semver.org/) as closely as possible but
will call out when or if we have to deviate from it. Our weekly releases will be
minor version increments and any bug or hotfixes between releases will go out as
patch versions on the most recent release.
Each Tuesday ~20:00 UTC new Stable and Preview releases will be cut. The
promotion flow is:
@@ -375,10 +375,9 @@ the main release file once service account permissions are sorted out.
## Release validation
After pushing a new release smoke testing should be performed to ensure that the
packages are working as expected. This can be done by installing the packages
locally and running a set of tests to ensure that they are functioning
correctly.
After pushing a new release, perform smoke testing to ensure that the packages
are working as expected. Install the packages locally and run a set of tests to
ensure that they are functioning correctly.
- `npx -y @google/gemini-cli@latest --version` to validate the push worked as
expected if you were not doing a rc or dev tag
@@ -386,8 +385,8 @@ correctly.
appropriately
- _This is destructive locally_
`npm uninstall @google/gemini-cli && npm uninstall -g @google/gemini-cli && npm cache clean --force && npm install @google/gemini-cli@<version>`
- Smoke testing a basic run through of exercising a few llm commands and tools
is recommended to ensure that the packages are working as expected. We'll
- Perform smoke testing of a basic run through of exercising a few llm commands
and tools to ensure that the packages are working as expected. Gemini CLI will
codify this more in the future.
## Local testing and validation: Changes to the packaging and publishing process
docs/resources/quota-and-pricing.md
+9 -12
View File
@@ -35,16 +35,15 @@ Generally, there are three categories to choose from:
- Pay-As-You-Go: The most flexible option for professional use, long-running
tasks, or when you need full control over your usage.
Requests are limited per user per minute and are subject to the availability of
the service in times of high demand.
Gemini CLI limits requests per user per minute and depends on the availability
of the service during times of high demand.
## Free usage
Access to Gemini CLI begins with a generous free tier, perfect for
experimentation and light use.
Your free usage is governed by the following limits, which depend on your
authorization type.
The following limits govern your free usage, based on your authorization type.
### Log in with Google (Gemini Code Assist for individuals)
@@ -52,8 +51,7 @@ For users who authenticate by using their Google account to access Gemini Code
Assist for individuals. This includes:
- 1000 maximum model requests / user / day
- Model requests will be made across the Gemini model family as determined by
Gemini CLI.
- Gemini CLI makes model requests across the Gemini model family.
Learn more at
[Gemini Code Assist for Individuals Limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
@@ -131,8 +129,7 @@ Standard/Plus and AI Expanded, are not supported._
- 1500 maximum model requests / user / day
- Gemini Code Assist Enterprise edition:
- 2000 maximum model requests / user / day
- Model requests will be made across the Gemini model family as determined by
Gemini CLI.
- Gemini CLI makes model requests across the Gemini model family.
[Learn more about Gemini Code Assist license limits](https://developers.google.com/gemini-code-assist/resources/quotas#quotas-for-agent-mode-gemini-cli).
@@ -171,10 +168,9 @@ Learn more at
[Gemini API Rate Limits](https://ai.google.dev/gemini-api/docs/rate-limits),
[Gemini API Pricing](https://ai.google.dev/gemini-api/docs/pricing)
It’s important to highlight that when using an API key, you pay per token/call.
It's important to highlight that when using an API key, you pay per token/call.
This can be more expensive for many small calls with few tokens, but it's the
only way to ensure your workflow isn't interrupted by reaching a limit on your
quota.
only way to ensure your workflow isn't interrupted by reaching a limit.
## Gemini for workspace plans
@@ -194,7 +190,8 @@ your current quota.
For more information on the `/stats` command and its subcommands, see the
[Command Reference](../reference/commands.md#stats).
A summary of model usage is also presented on exit at the end of a session.
Gemini CLI also presents a summary of model usage on exit at the end of a
session.
## Tips to avoid high costs