gemini-cli/docs/tools/planning.md

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.

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.