|
|
|
|
@@ -62,8 +62,11 @@ To start Plan Mode while using Gemini CLI:
|
|
|
|
|
- **Command:** Type `/plan` in the input box.
|
|
|
|
|
|
|
|
|
|
- **Natural Language:** Ask Gemini CLI to "start a plan for...". Gemini CLI
|
|
|
|
|
calls the [`enter_plan_mode`] tool to switch modes.
|
|
|
|
|
> **Note:** This tool is not available when Gemini CLI is in [YOLO mode].
|
|
|
|
|
calls the
|
|
|
|
|
[`enter_plan_mode`](../tools/planning.md#1-enter_plan_mode-enterplanmode) tool
|
|
|
|
|
to switch modes.
|
|
|
|
|
> **Note:** This tool is not available when Gemini CLI is in
|
|
|
|
|
> [YOLO mode](../reference/configuration.md#command-line-arguments).
|
|
|
|
|
|
|
|
|
|
## How to use Plan Mode
|
|
|
|
|
|
|
|
|
|
@@ -74,7 +77,8 @@ Gemini CLI takes action.
|
|
|
|
|
will then enter Plan Mode (if it's not already) to research the task.
|
|
|
|
|
2. **Review research and provide input:** As Gemini CLI analyzes your codebase,
|
|
|
|
|
it may ask you questions or present different implementation options using
|
|
|
|
|
[`ask_user`]. Provide your preferences to help guide the design.
|
|
|
|
|
[`ask_user`](../tools/ask-user.md). Provide your preferences to help guide
|
|
|
|
|
the design.
|
|
|
|
|
3. **Review the plan:** Once Gemini CLI has a proposed strategy, it creates a
|
|
|
|
|
detailed implementation plan as a Markdown file in your plans directory. You
|
|
|
|
|
can open and read this file to understand the proposed changes.
|
|
|
|
|
@@ -116,25 +120,33 @@ Plan Mode enforces strict safety policies to prevent accidental changes.
|
|
|
|
|
|
|
|
|
|
These are the only allowed tools:
|
|
|
|
|
|
|
|
|
|
- **FileSystem (Read):** [`read_file`], [`list_directory`], [`glob`]
|
|
|
|
|
- **Search:** [`grep_search`], [`google_web_search`]
|
|
|
|
|
- **Research Subagents:** [`codebase_investigator`], [`cli_help`]
|
|
|
|
|
- **Interaction:** [`ask_user`]
|
|
|
|
|
- **MCP tools (Read):** Read-only [MCP tools] (for example, `github_read_issue`,
|
|
|
|
|
`postgres_read_schema`) are allowed.
|
|
|
|
|
- **Planning (Write):** [`write_file`] and [`replace`] only allowed for `.md`
|
|
|
|
|
- **FileSystem (Read):**
|
|
|
|
|
[`read_file`](../tools/file-system.md#2-read_file-readfile),
|
|
|
|
|
[`list_directory`](../tools/file-system.md#1-list_directory-readfolder),
|
|
|
|
|
[`glob`](../tools/file-system.md#4-glob-findfiles)
|
|
|
|
|
- **Search:** [`grep_search`](../tools/file-system.md#5-grep_search-searchtext),
|
|
|
|
|
[`google_web_search`](../tools/web-search.md)
|
|
|
|
|
- **Research Subagents:**
|
|
|
|
|
[`codebase_investigator`](../core/subagents.md#codebase-investigator),
|
|
|
|
|
[`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.
|
|
|
|
|
- **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`
|
|
|
|
|
files in the `~/.gemini/tmp/<project>/<session-id>/plans/` directory or your
|
|
|
|
|
[custom plans directory](#custom-plan-directory-and-policies).
|
|
|
|
|
- **Memory:** [`save_memory`]
|
|
|
|
|
- **Skills:** [`activate_skill`] (allows loading specialized instructions and
|
|
|
|
|
resources in a read-only manner)
|
|
|
|
|
- **Memory:** [`save_memory`](../tools/memory.md)
|
|
|
|
|
- **Skills:** [`activate_skill`](../cli/skills.md) (allows loading specialized
|
|
|
|
|
instructions and resources in a read-only manner)
|
|
|
|
|
|
|
|
|
|
### Custom planning with skills
|
|
|
|
|
|
|
|
|
|
You can use [Agent Skills] to customize how Gemini CLI approaches planning for
|
|
|
|
|
specific types of tasks. When a skill is activated during Plan Mode, its
|
|
|
|
|
specialized instructions and procedural workflows will guide the research,
|
|
|
|
|
design, and planning phases.
|
|
|
|
|
You can use [Agent Skills](../cli/skills.md) to customize how Gemini CLI
|
|
|
|
|
approaches planning for specific types of tasks. When a skill is activated
|
|
|
|
|
during Plan Mode, its specialized instructions and procedural workflows will
|
|
|
|
|
guide the research, design, and planning phases.
|
|
|
|
|
|
|
|
|
|
For example:
|
|
|
|
|
|
|
|
|
|
@@ -151,10 +163,11 @@ based on the task description.
|
|
|
|
|
|
|
|
|
|
### Custom policies
|
|
|
|
|
|
|
|
|
|
Plan Mode's default tool restrictions are managed by the [policy engine] and
|
|
|
|
|
defined in the built-in [`plan.toml`] file. The built-in policy (Tier 1)
|
|
|
|
|
enforces the read-only state, but you can customize these rules by creating your
|
|
|
|
|
own policies in your `~/.gemini/policies/` directory (Tier 2).
|
|
|
|
|
Plan Mode's default tool restrictions are managed by the
|
|
|
|
|
[policy engine](../reference/policy-engine.md) and defined in the built-in
|
|
|
|
|
[`plan.toml`] file. The built-in policy (Tier 1) enforces the read-only state,
|
|
|
|
|
but you can customize these rules by creating your own policies in your
|
|
|
|
|
`~/.gemini/policies/` directory (Tier 2).
|
|
|
|
|
|
|
|
|
|
#### Example: Automatically approve read-only MCP tools
|
|
|
|
|
|
|
|
|
|
@@ -173,8 +186,8 @@ priority = 100
|
|
|
|
|
modes = ["plan"]
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
For more information on how the policy engine works, see the [policy engine]
|
|
|
|
|
docs.
|
|
|
|
|
For more information on how the policy engine works, see the
|
|
|
|
|
[policy engine](../reference/policy-engine.md) docs.
|
|
|
|
|
|
|
|
|
|
#### Example: Allow git commands in Plan Mode
|
|
|
|
|
|
|
|
|
|
@@ -194,9 +207,12 @@ modes = ["plan"]
|
|
|
|
|
|
|
|
|
|
#### Example: Enable custom subagents in Plan Mode
|
|
|
|
|
|
|
|
|
|
Built-in research [subagents] like [`codebase_investigator`] and [`cli_help`]
|
|
|
|
|
are enabled by default in Plan Mode. You can enable additional [custom
|
|
|
|
|
subagents] by adding a rule to your policy.
|
|
|
|
|
Built-in research [subagents](../core/subagents.md) like
|
|
|
|
|
[`codebase_investigator`](../core/subagents.md#codebase-investigator) and
|
|
|
|
|
[`cli_help`](../core/subagents.md#cli-help-agent) are enabled by default in Plan
|
|
|
|
|
Mode. You can enable additional
|
|
|
|
|
[custom subagents](../core/subagents.md#creating-custom-subagents) by adding a
|
|
|
|
|
rule to your policy.
|
|
|
|
|
|
|
|
|
|
`~/.gemini/policies/research-subagents.toml`
|
|
|
|
|
|
|
|
|
|
@@ -235,10 +251,11 @@ locations defined within a project's workspace cannot be used to escape and
|
|
|
|
|
overwrite sensitive files elsewhere. Any user-configured directory must reside
|
|
|
|
|
within the project boundary.
|
|
|
|
|
|
|
|
|
|
Using a custom directory requires updating your [policy engine] configurations
|
|
|
|
|
to allow `write_file` and `replace` in that specific location. For example, to
|
|
|
|
|
allow writing to the `.gemini/plans` directory within your project, create a
|
|
|
|
|
policy file at `~/.gemini/policies/plan-custom-directory.toml`:
|
|
|
|
|
Using a custom directory requires updating your
|
|
|
|
|
[policy engine](../reference/policy-engine.md) configurations to allow
|
|
|
|
|
`write_file` and `replace` in that specific location. For example, to allow
|
|
|
|
|
writing to the `.gemini/plans` directory within your project, create a policy
|
|
|
|
|
file at `~/.gemini/policies/plan-custom-directory.toml`:
|
|
|
|
|
|
|
|
|
|
```toml
|
|
|
|
|
[[rule]]
|
|
|
|
|
@@ -254,13 +271,16 @@ argsPattern = "\"file_path\":\"[^\"]+[\\\\/]+\\.gemini[\\\\/]+plans[\\\\/]+[\\w-
|
|
|
|
|
## Planning workflows
|
|
|
|
|
|
|
|
|
|
Plan Mode provides building blocks for structured research and design. These are
|
|
|
|
|
implemented as [extensions] using core planning tools like [`enter_plan_mode`],
|
|
|
|
|
[`exit_plan_mode`], and [`ask_user`].
|
|
|
|
|
implemented as [extensions](../extensions/index.md) using core planning tools
|
|
|
|
|
like [`enter_plan_mode`](../tools/planning.md#1-enter_plan_mode-enterplanmode),
|
|
|
|
|
[`exit_plan_mode`](../tools/planning.md#2-exit_plan_mode-exitplanmode), and
|
|
|
|
|
[`ask_user`](../tools/ask-user.md).
|
|
|
|
|
|
|
|
|
|
### Built-in planning workflow
|
|
|
|
|
|
|
|
|
|
The built-in planner uses an adaptive workflow to analyze your project, consult
|
|
|
|
|
you on trade-offs via [`ask_user`], and draft a plan for your approval.
|
|
|
|
|
you on trade-offs via [`ask_user`](../tools/ask-user.md), and draft a plan for
|
|
|
|
|
your approval.
|
|
|
|
|
|
|
|
|
|
### Custom planning workflows
|
|
|
|
|
|
|
|
|
|
@@ -272,23 +292,29 @@ You can install or create specialized planners to suit your workflow.
|
|
|
|
|
"tracks" and stores persistent artifacts in your project's `conductor/`
|
|
|
|
|
directory:
|
|
|
|
|
|
|
|
|
|
- **Automate transitions:** Switches to read-only mode via [`enter_plan_mode`].
|
|
|
|
|
- **Streamline decisions:** Uses [`ask_user`] for architectural choices.
|
|
|
|
|
- **Automate transitions:** Switches to read-only mode via
|
|
|
|
|
[`enter_plan_mode`](../tools/planning.md#1-enter_plan_mode-enterplanmode).
|
|
|
|
|
- **Streamline decisions:** Uses [`ask_user`](../tools/ask-user.md) for
|
|
|
|
|
architectural choices.
|
|
|
|
|
- **Maintain project context:** Stores artifacts in the project directory using
|
|
|
|
|
[custom plan directory and policies](#custom-plan-directory-and-policies).
|
|
|
|
|
- **Handoff execution:** Transitions to implementation via [`exit_plan_mode`].
|
|
|
|
|
- **Handoff execution:** Transitions to implementation via
|
|
|
|
|
[`exit_plan_mode`](../tools/planning.md#2-exit_plan_mode-exitplanmode).
|
|
|
|
|
|
|
|
|
|
#### Build your own
|
|
|
|
|
|
|
|
|
|
Since Plan Mode is built on modular building blocks, you can develop your own
|
|
|
|
|
custom planning workflow as an [extensions]. By leveraging core tools and
|
|
|
|
|
[custom policies](#custom-policies), you can define how Gemini CLI researches
|
|
|
|
|
and stores plans for your specific domain.
|
|
|
|
|
custom planning workflow as an [extensions](../extensions/index.md). By
|
|
|
|
|
leveraging core tools and [custom policies](#custom-policies), you can define
|
|
|
|
|
how Gemini CLI researches and stores plans for your specific domain.
|
|
|
|
|
|
|
|
|
|
To build a custom planning workflow, you can use:
|
|
|
|
|
|
|
|
|
|
- **Tool usage:** Use core tools like [`enter_plan_mode`], [`ask_user`], and
|
|
|
|
|
[`exit_plan_mode`] to manage the research and design process.
|
|
|
|
|
- **Tool usage:** Use core tools like
|
|
|
|
|
[`enter_plan_mode`](../tools/planning.md#1-enter_plan_mode-enterplanmode),
|
|
|
|
|
[`ask_user`](../tools/ask-user.md), and
|
|
|
|
|
[`exit_plan_mode`](../tools/planning.md#2-exit_plan_mode-exitplanmode) to
|
|
|
|
|
manage the research and design process.
|
|
|
|
|
- **Customization:** Set your own storage locations and policy rules using
|
|
|
|
|
[custom plan directories](#custom-plan-directory-and-policies) and
|
|
|
|
|
[custom policies](#custom-policies).
|
|
|
|
|
@@ -302,8 +328,9 @@ high-reasoning model routing.
|
|
|
|
|
|
|
|
|
|
## Automatic Model Routing
|
|
|
|
|
|
|
|
|
|
When using an [auto model], Gemini CLI automatically optimizes [model routing]
|
|
|
|
|
based on the current phase of your task:
|
|
|
|
|
When using an [auto model](../reference/configuration.md#model), Gemini CLI
|
|
|
|
|
automatically optimizes [model routing](../cli/telemetry.md#model-routing) based
|
|
|
|
|
on the current phase of your task:
|
|
|
|
|
|
|
|
|
|
1. **Planning Phase:** While in Plan Mode, the CLI routes requests to a
|
|
|
|
|
high-reasoning **Pro** model to ensure robust architectural decisions and
|
|
|
|
|
@@ -334,7 +361,8 @@ associated plan files and task trackers.
|
|
|
|
|
- **Default behavior:** Sessions (and their plans) are retained for **30 days**.
|
|
|
|
|
- **Configuration:** You can customize this behavior via the `/settings` command
|
|
|
|
|
(search for **Session Retention**) or in your `settings.json` file. See
|
|
|
|
|
[session retention] for more details.
|
|
|
|
|
[session retention](../cli/session-management.md#session-retention) for more
|
|
|
|
|
details.
|
|
|
|
|
|
|
|
|
|
Manual deletion also removes all associated artifacts:
|
|
|
|
|
|
|
|
|
|
@@ -344,32 +372,7 @@ Manual deletion also removes all associated artifacts:
|
|
|
|
|
If you use a [custom plans directory](#custom-plan-directory-and-policies),
|
|
|
|
|
those files are not automatically deleted and must be managed manually.
|
|
|
|
|
|
|
|
|
|
[`list_directory`]: /docs/tools/file-system.md#1-list_directory-readfolder
|
|
|
|
|
[`read_file`]: /docs/tools/file-system.md#2-read_file-readfile
|
|
|
|
|
[`grep_search`]: /docs/tools/file-system.md#5-grep_search-searchtext
|
|
|
|
|
[`write_file`]: /docs/tools/file-system.md#3-write_file-writefile
|
|
|
|
|
[`glob`]: /docs/tools/file-system.md#4-glob-findfiles
|
|
|
|
|
[`google_web_search`]: /docs/tools/web-search.md
|
|
|
|
|
[`replace`]: /docs/tools/file-system.md#6-replace-edit
|
|
|
|
|
[MCP tools]: /docs/tools/mcp-server.md
|
|
|
|
|
[`save_memory`]: /docs/tools/memory.md
|
|
|
|
|
[`activate_skill`]: /docs/cli/skills.md
|
|
|
|
|
[`codebase_investigator`]: /docs/core/subagents.md#codebase-investigator
|
|
|
|
|
[`cli_help`]: /docs/core/subagents.md#cli-help-agent
|
|
|
|
|
[subagents]: /docs/core/subagents.md
|
|
|
|
|
[custom subagents]: /docs/core/subagents.md#creating-custom-subagents
|
|
|
|
|
[policy engine]: /docs/reference/policy-engine.md
|
|
|
|
|
[`enter_plan_mode`]: /docs/tools/planning.md#1-enter_plan_mode-enterplanmode
|
|
|
|
|
[`exit_plan_mode`]: /docs/tools/planning.md#2-exit_plan_mode-exitplanmode
|
|
|
|
|
[`ask_user`]: /docs/tools/ask-user.md
|
|
|
|
|
[YOLO mode]: /docs/reference/configuration.md#command-line-arguments
|
|
|
|
|
[`plan.toml`]:
|
|
|
|
|
https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policies/plan.toml
|
|
|
|
|
[auto model]: /docs/reference/configuration.md#model
|
|
|
|
|
[model routing]: /docs/cli/telemetry.md#model-routing
|
|
|
|
|
[preferred external editor]: /docs/reference/configuration.md#general
|
|
|
|
|
[session retention]: /docs/cli/session-management.md#session-retention
|
|
|
|
|
[extensions]: /docs/extensions/
|
|
|
|
|
[Conductor]: https://github.com/gemini-cli-extensions/conductor
|
|
|
|
|
[open an issue]: https://github.com/google-gemini/gemini-cli/issues
|
|
|
|
|
[Agent Skills]: /docs/cli/skills.md
|
|
|
|
|
|
Chris Williams