Overview
The node integrates with the Google Gemini CLI to perform AI-powered coding and planning tasks using multimodal capabilities. It supports operations such as executing approved plans, generating new execution plans, editing existing plans, approving plans, querying the Gemini model for code or analysis, continuing conversations, and listing stored plans.
This node is beneficial in scenarios where automated, structured task planning and execution are needed, especially for software development workflows. For example, it can generate detailed step-by-step execution plans for complex coding tasks, modify those plans based on new instructions, approve them for execution, and then execute each step while tracking progress and status.
Practical examples:
- Automatically generate a plan to implement a new feature in a project.
- Edit an existing plan to add error handling or extend functionality.
- Approve a plan after review and execute it step-by-step, applying code changes or running commands.
- Query the Gemini model for coding assistance or analysis within a project directory.
Properties
| Name | Meaning |
|---|---|
| Plan ID | The unique identifier of the execution plan to work with (required for edit_plan, approve_plan, execute_plan operations). Example: "plan_20240108_123456". |
| Model | The Gemini AI model to use: - 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 (back-and-forth exchanges) allowed during query or conversation continuation. |
| Timeout | Maximum time in seconds to wait for Gemini CLI completion before aborting the operation. |
| Project Path | Directory path where Gemini CLI should run. If empty, uses the current working directory. This allows Gemini CLI to access files and run commands in the specified project location. |
| Output Format | How to format the output data: - Messages: Raw array of all messages exchanged. - Plan: Execution plan structure (for plan-related operations). - Plan Status: Progress and status of plan execution. - Structured: Object with messages, summary, result, and metrics. - Text: Only the 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: Additional context/instructions for Gemini CLI. - Debug Mode: Enable debug logging. |
| Tools Configuration | Configure built-in tools and external integrations: - Enable Built-in Tools: File system read/write, shell commands, web fetch, web search. - Security Mode: Safe mode (confirmations required), auto-approve (YOLO), sandbox mode. - Enable Checkpointing: Save conversation state. |
| MCP Servers | Configure external MCP servers for extended functionality: - Multiple server configurations with command or HTTP connection. - Environment variables, headers, include/exclude tools, trust level, working directory, timeout, etc. |
Output
The node outputs JSON data whose structure depends on the selected operation and output format:
- Messages: An array of message objects exchanged with Gemini CLI, including user inputs, assistant responses, and errors.
- Plan: The full execution plan object containing:
id: Plan identifier.title: Brief title of the task.description: Detailed description.steps: Array of steps, each withid,description, optionalcommand, optionalfilesarray, estimated duration, and status.created_at,modified_at,status, and other metadata.
- Plan Status: Current progress of plan execution, including counts of completed and failed steps, and overall status (
completed,failed,executing). - Structured: A comprehensive object including messages, summary statistics (counts of user/assistant/error messages), the final result text, performance metrics, configuration details, success flag, and any error messages.
- Text: Only the final textual result from Gemini CLI.
If binary data were supported (not indicated here), it would be summarized accordingly, but this node focuses on JSON/textual data.
Dependencies
- Requires the Gemini CLI installed and accessible in the system PATH (
geminicommand). - Optionally requires a valid API key credential for Gemini API or Vertex AI, either provided via node parameters or environment variables.
- Uses Node.js child process APIs to spawn Gemini CLI commands.
- Access to the file system for reading/writing plans and optionally running commands in the specified project directory.
- Optional external MCP servers configured for extended tool integrations.
- n8n environment must allow execution of child processes and have permissions for the specified project paths.
Troubleshooting
- Gemini CLI Not Available: Error if the Gemini CLI is not installed or not found in PATH. Install it globally with
npm install -g @google/gemini-cli. - Invalid Project Path: If the specified project path does not exist, is not a directory, or lacks read/write permissions, the node will throw an error. Verify the path and permissions.
- Missing Required Parameters: Operations like
execute_plan,edit_plan, andapprove_planrequire a valid Plan ID;query,continue, andgenerate_planrequire a non-empty prompt. - Plan Not Found: Attempting to load a plan by ID that does not exist results in an error.
- Plan Not Approved: Executing a plan that is not in "approved" status will fail.
- Timeouts: Gemini CLI operations may time out if they exceed the configured timeout value.
- Parsing Errors: If Gemini CLI returns invalid or unexpected JSON for plans, the node throws parsing errors.
- Security Risks: Enabling shell commands or auto-approve modes can be dangerous; use caution.
- Debugging: Enable debug mode to get detailed logs for troubleshooting.
Links and References
- Google Gemini CLI GitHub Repository (hypothetical link)
- n8n Documentation on Creating Custom Nodes
- Node.js Child Process Documentation
- Model Context Protocol (MCP) (for MCP server integration)
This summary covers the logic and usage of the "Execute Plan" operation within the Gemini CLI node, focusing on how it loads an approved plan, executes each step sequentially by sending instructions to Gemini CLI, updates step statuses, and returns the updated plan and execution results.