gemini-cli/docs/cli/plan-mode.md

Plan Mode (experimental)

Plan Mode is a safe, read-only mode for researching and designing complex changes. It prevents modifications while you research, design and plan an implementation strategy.

Note: Plan Mode is currently an experimental feature.

Experimental features are subject to change. To use Plan Mode, enable it via /settings (search for Plan) or add the following to your settings.json:

{
  "experimental": {
    "plan": true
  }
}

Your feedback is invaluable as we refine this feature. If you have ideas, suggestions, or encounter issues:

• Use the /bug command within the CLI to file an issue.
• Open an issue on GitHub.

• Starting in Plan Mode
• How to use Plan Mode
  • Entering Plan Mode
  • The Planning Workflow
  • Exiting Plan Mode
• Tool Restrictions
  • Customizing Planning with Skills
  • Customizing Policies

Starting in Plan Mode

You can configure Gemini CLI to start directly in Plan Mode by default:

1. Type /settings in the CLI.
2. Search for Default Approval Mode.
3. Set the value to Plan.

Other ways to start in Plan Mode:

• CLI Flag: gemini --approval-mode=plan

• Manual Settings: Manually update your settings.json:

  {
    "general": {
      "defaultApprovalMode": "plan"
    }
  }
  

How to use Plan Mode

Entering Plan Mode

You can enter Plan Mode in three ways:

1. Keyboard Shortcut: Press Shift+Tab to cycle through approval modes (Default -> Auto-Edit -> Plan).

   Note: Plan Mode is automatically removed from the rotation when the agent is actively processing or showing confirmation dialogs.

2. Command: Type /plan in the input box.

3. Natural Language: Ask the agent to "start a plan for...". The agent will then call the enter_plan_mode tool to switch modes.

The Planning Workflow

1. Requirements: The agent clarifies goals using ask_user.
2. Exploration: The agent uses read-only tools (like read_file) to map the codebase and validate assumptions.
3. Design: The agent proposes alternative approaches with a recommended solution for you to choose from.
4. Planning: A detailed plan is written to a temporary Markdown file.
5. Review: You review the plan.
   • Approve: Exit Plan Mode and start implementation (switching to Auto-Edit or Default approval mode).
   • Iterate: Provide feedback to refine the plan.

Exiting Plan Mode

To exit Plan Mode:

1. Keyboard Shortcut: Press Shift+Tab to cycle to the desired mode.
2. Tool: The agent calls the exit_plan_mode tool to present the finalized plan for your approval.

Tool Restrictions

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
• Interaction: ask_user
• MCP Tools (Read): Read-only MCP tools (e.g., github_read_issue, postgres_read_schema) are allowed.
• Planning (Write): write_file and replace ONLY allowed for .md files in the ~/.gemini/tmp/<project>/<session-id>/plans/ directory.
• Skills: activate_skill (allows loading specialized instructions and resources in a read-only manner)

Customizing the Plan Directory

By default, plans are stored in a temporary directory within ~/.gemini/tmp/. You can customize this location, but doing so requires two steps: configuring the setting and adding a policy rule.

Important: If you only update settings.json, the agent will be blocked from writing to your custom directory by the default safety policies.

1. Configure the directory in settings.json

Add the plan.directory setting to your ~/.gemini/settings.json file. This path can be absolute or relative to your project root.

{
  "general": {
    "plan": {
      "directory": "conductor"
    }
  }
}

2. Add a policy to allow writing to that directory

Create a policy file (e.g., ~/.gemini/policies/custom-plans.toml) to explicitly allow the agent to write files to your custom directory while in Plan Mode.

The argsPattern in your policy must match the file_path (or path) argument passed to the tool.

[[rule]]
toolName = ["write_file", "replace"]
# Allow writing to any path within the "conductor/" directory
# This regex matches a relative path.
argsPattern = "\"(?:file_path|path)\":\"conductor/[^\"]+\""
decision = "allow"
priority = 100
modes = ["plan"]

Relative vs. Absolute Paths:

• Relative Paths: If you use a relative path like "conductor" in settings.json, the agent will typically use conductor/plan.md. Your argsPattern should reflect this relative structure.
• Absolute Paths: If you use an absolute path like "/usr/local/plans", your argsPattern must match that absolute path: \"(?:file_path|path)\":\"/usr/local/plans/[^\"]+\".

Tip: For Windows users, the regex pattern must match double-backslashes in the JSON-stringified arguments: conductor\\\\[^"]+.

Customizing Planning with Skills

You can leverage 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 and design phases.

For example:

• A "Database Migration" skill could ensure the plan includes data safety checks and rollback strategies.
• A "Security Audit" skill could prompt the agent to look for specific vulnerabilities during codebase exploration.
• A "Frontend Design" skill could guide the agent to use specific UI components and accessibility standards in its proposal.

To use a skill in Plan Mode, you can explicitly ask the agent to "use the [skill-name] skill to plan..." or the agent may autonomously activate it based on the task description.

Customizing Policies

Plan Mode is designed to be read-only by default to ensure safety during the research phase. However, you may occasionally need to allow specific tools to assist in your planning.

Because user policies (Tier 2) have a higher base priority than built-in policies (Tier 1), you can override Plan Mode's default restrictions by creating a rule in your ~/.gemini/policies/ directory.

Example: Allow git status and git diff in Plan Mode

This rule allows you to check the repository status and see changes while in Plan Mode.

~/.gemini/policies/git-research.toml

[[rule]]
toolName = "run_shell_command"
commandPrefix = ["git status", "git diff"]
decision = "allow"
priority = 100
modes = ["plan"]

Example: Enable research sub-agents in Plan Mode

You can enable experimental research sub-agents like codebase_investigator to help gather architecture details during the planning phase.

~/.gemini/policies/research-subagents.toml

[[rule]]
toolName = "codebase_investigator"
decision = "allow"
priority = 100
modes = ["plan"]

Tell the agent it can use these tools in your prompt, for example: "You can check ongoing changes in git."

For more information on how the policy engine works, see the Policy Engine Guide.