Overview
The "Edit Plan" operation of the Gemini CLI node allows users to modify an existing AI-generated execution plan. This plan consists of a structured set of steps designed to accomplish a coding or project-related task. By providing specific edit instructions, users can update the plan’s title, description, and individual steps without losing the original structure.
This operation is beneficial in scenarios where an initial plan needs refinement or adjustment based on new requirements or feedback. For example, if a plan lacks error handling or requires changes in step timeouts, users can instruct the node to apply these modifications automatically.
Practical examples:
- Adding error handling to a particular step in a software deployment plan.
- Increasing timeout durations for long-running tasks within the plan.
- Adjusting commands or files associated with certain steps based on updated project needs.
Properties
| Name | Meaning |
|---|---|
| Plan ID | The unique identifier of the existing plan to be edited (e.g., "plan_20240108_123456"). Required to specify which plan to modify. |
| Edit Instructions | Textual instructions describing how to modify the plan (e.g., "Add error handling to step 2 and increase timeout for step 4"). These guide the AI assistant in updating the plan accordingly. |
| Model | The Gemini AI model to use for processing the edit. Options: • Gemini 2.5 Pro — Most capable model with 1M token context window • Gemini 2.5 Flash — Fast and efficient model for quick responses |
| Max Turns | Maximum number of conversation turns allowed during interaction with Gemini CLI. Controls the back-and-forth exchanges limit. |
| Timeout | Maximum time in seconds to wait for the Gemini CLI process to complete before aborting. |
| Project Path | Directory path where Gemini CLI runs, allowing access to project files and commands. If empty, defaults to current working directory. |
| Output Format | Format of the output data returned by the node. Options: • Messages — Raw array of all exchanged messages • Plan — Execution plan structure • Plan Status — Progress and status of plan execution • Structured — Object with messages, summary, result, metrics • Text — Only final result text |
| Additional Options | Collection of optional settings: • API Key — Gemini API key if not set via environment variable • Use Vertex AI — Whether to use Vertex AI instead of Gemini API • System Prompt — Extra context/instructions for Gemini CLI • Debug Mode — Enable debug logging |
| Tools Configuration | Configure built-in tools and integrations: • Enable Built-in Tools — File system, shell commands, web fetch, web search • Security Mode — Safe mode (confirmations), auto-approve (YOLO), sandbox mode • Enable Checkpointing — Save conversation state |
| MCP Servers | Configure external MCP servers for extended functionality, including connection type, commands, environment variables, tool inclusion/exclusion, headers, and trust level. |
Output
The output JSON structure depends on the selected Output Format:
- Messages: Returns an array of all messages exchanged during the Gemini CLI interaction, including user inputs, assistant responses, and errors.
- Plan: Returns the full execution plan object after editing, including updated title, description, steps, timestamps, and status.
- Plan Status: Not typically used for edit operation output.
- Structured: Returns a detailed object containing:
messages: All exchanged messages.summary: Counts of user, assistant, and error messages plus whether a result exists.result: The raw textual result from Gemini CLI.metrics: Duration and number of turns.configuration: Details about model, enabled tools, security mode, checkpointing, MCP servers, and project path.success: Boolean indicating success.error: Any error message if occurred.
- Text: Returns only the final textual result from the Gemini CLI response.
The edited plan structure includes:
id: Plan ID.title: Updated plan title.description: Updated plan description.steps: Array of steps, each with:id: Step identifier.description: Step details.command: Optional command to run.files: Optional list of files involved.estimated_duration: Estimated time in seconds.status: Step status (e.g., "pending").
Dependencies
- Requires the Gemini CLI installed and accessible in the system PATH.
- Optionally requires a Gemini API key credential or environment variable for authentication.
- Supports integration with Vertex AI as an alternative backend.
- May require proper permissions and existence of the specified project directory.
- External MCP servers can be configured for extended capabilities.
- Node uses child process spawning to run the Gemini CLI commands.
Troubleshooting
- Gemini CLI Not Available: Error indicating Gemini CLI is not installed or not found in PATH. Solution: Install Gemini CLI globally (
npm install -g @google/gemini-cli) and ensure it is accessible. - Invalid Project Path: If the provided project path does not exist, is not a directory, or lacks read/write permissions, the node will throw an error. Verify the path correctness and permissions.
- Plan Not Found: When the specified Plan ID does not correspond to any saved plan, an error is thrown. Confirm the Plan ID is correct and that the plan exists in the
.gemini/plansdirectory. - Invalid Plan Structure: If the Gemini CLI response cannot be parsed into a valid plan JSON structure, the node throws an error. This may indicate malformed AI output or communication issues.
- Timeouts: If Gemini CLI takes longer than the specified timeout, the process is aborted. Increase the timeout value if necessary.
- Authentication Issues: If Gemini CLI is installed but not properly authenticated (missing API key), operations will fail. Provide a valid API key either via input property or environment variable.
- Debug Mode: Enabling debug mode helps trace internal logs and identify issues during execution.