Overview
This node integrates with the Google Gemini CLI to perform AI-powered coding and project management tasks using conversational prompts. It supports multiple operations such as starting new conversations, continuing existing ones, generating detailed execution plans for tasks, editing and approving those plans, executing approved plans step-by-step, and listing stored plans.
Typical use cases include:
- Automating code generation or modification based on natural language instructions.
- Creating structured execution plans for complex development tasks.
- Managing and executing multi-step workflows programmatically.
- Leveraging AI assistance for project-related commands within a specified directory context.
For example, you can prompt the node to "Create a Python function to parse CSV files," generate an execution plan breaking down the task into steps, approve and execute that plan, all while optionally enabling tools like file system access or shell command execution.
Properties
| Name | Meaning |
|---|---|
| Prompt | The instruction or query sent to Gemini CLI. Required for operations query, continue, and generate_plan. Supports expressions to dynamically use data from previous nodes. |
| Model | Selects the Gemini model to use: - Gemini 2.5 Pro: Most capable with 1M token context window - Gemini 2.5 Flash: Faster, efficient for quick responses |
| Max Turns | Maximum number of conversation turns (back-and-forth exchanges) allowed in the session. |
| Timeout | Maximum time in seconds to wait for Gemini CLI completion before aborting. |
| Project Path | Directory path where Gemini CLI runs, allowing it to access files and run commands in that location. If empty, uses current working directory. |
| Output Format | How to format the output data: - Messages: Raw array of all exchanged messages - Plan: Execution plan structure (for plan operations) - Plan Status: Progress/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 - Debug Mode: Enable debug logging |
| Tools Configuration | Configure built-in tools and integrations: - Enable Built-in Tools: File system read/write, shell commands, web fetch, web search - Security Mode: Safe (confirmations required), Auto-Approve (YOLO), Sandbox - Enable Checkpointing: Save conversation state |
| MCP Servers | Configure external MCP servers for extended functionality: - Command or HTTP connection types - Environment variables, headers, included/excluded tools - Trust level for tool calls - Working directory and timeout settings |
Output
The node outputs JSON objects whose structure depends on the selected operation and output format:
- Messages: An array of message objects representing the full conversation exchange, including user inputs, assistant responses, and errors.
- Plan: A structured execution plan object containing:
id: Unique plan identifiertitle: Brief title of the taskdescription: Detailed descriptionsteps: Array of steps, each withid,description, optionalcommand, optionalfilesarray, estimated duration, and status
- Plan Status: Current progress and status of a plan execution, including counts of completed and failed steps.
- Structured: A comprehensive object including messages, summary statistics (counts of user/assistant/error messages), the final result text, performance metrics (duration, number of turns), configuration details, success flag, and error info if any.
- Text: Only the final textual result from Gemini CLI.
When executing plans, the output includes both the updated plan with step statuses and detailed results per step.
The node does not output binary data.
Dependencies
- Requires the Gemini CLI installed and accessible in the system PATH (
geminicommand). - Optionally requires a valid API key for Gemini API, either provided in node parameters or set as an environment variable.
- Supports integration with Vertex AI if enabled.
- May require appropriate permissions for the specified project directory.
- External MCP servers can be configured for extended capabilities.
- Node uses child process spawning to run Gemini CLI commands.
Troubleshooting
- Gemini CLI Not Found: Error indicating Gemini CLI is not installed or not in PATH. Fix by installing it globally (
npm install -g @google/gemini-cli) and ensuring accessibility. - Invalid Project Path: Errors occur if the specified project directory does not exist, is not a directory, or lacks read/write permissions. Verify the path and permissions.
- Missing Required Parameters: Operations like
queryrequire a non-empty prompt; plan-related operations require a valid plan ID. - Timeouts: Long-running Gemini CLI commands may time out based on the configured timeout setting. Increase timeout if needed.
- Plan Not Found: When editing, approving, or executing a plan, if the plan ID does not correspond to a saved plan, an error is thrown.
- Plan Not Approved: Attempting to execute a plan that is not marked as approved will fail.
- JSON Parsing Errors: If Gemini CLI returns malformed or unexpected output when generating or editing plans, parsing errors occur. Ensure prompts and system instructions are clear.
- Security Risks: Enabling shell commands or auto-approve modes can be dangerous. Use safe mode and confirmations unless you fully trust the environment.
Enabling debug mode provides detailed logs to help diagnose issues.