Overview
This node integrates with the Claude Code AI SDK to perform AI-powered coding tasks through conversational interactions. It allows users to send prompts or instructions to Claude Code, which can generate code, create plans for tasks, continue conversations, approve and execute plans, or test project directory paths.
Common scenarios include:
- Generating code snippets or functions based on natural language prompts.
- Creating detailed or high-level plans for software development tasks without immediate execution.
- Approving and executing previously created plans with optional modifications.
- Continuing ongoing conversations with Claude Code to refine or extend previous outputs.
- Validating project directory paths before running code generation or execution.
Practical examples:
- Asking Claude Code to "Create a Python function to parse CSV files" and receiving the generated code.
- Requesting a step-by-step plan to implement a new feature in a project.
- Approving a generated plan with added error handling instructions before execution.
- Testing if a specified project path exists and has proper permissions before running commands.
Properties
| Name | Meaning |
|---|---|
| Prompt | The instruction or query sent to Claude Code. Supports expressions to dynamically use data from previous nodes. Example: "Create a Python function to parse CSV files" |
| Model | Selects the Claude model variant: - Sonnet: Fast and efficient for most tasks - Opus: More capable for complex tasks |
| Max Turns | Maximum number of back-and-forth conversation turns allowed during the interaction. |
| Timeout | Maximum time (in seconds) to wait for Claude Code's response before aborting the operation. |
| Project Path | Directory path where Claude Code should run, allowing access to files and command execution within that location. If empty, uses the current working directory. |
| Output Format | Determines the format of the output data: - Structured: Object containing messages, summary, result, and metrics - Messages: Raw array of all exchanged messages - Text: Only the final result text |
| Allowed Tools | Built-in tools Claude Code is permitted to use during execution. Options include: Bash, Edit, Exit Plan Mode, Glob, Grep, LS, MultiEdit, Notebook Edit/Read, Read, Task, Todo Write, Web Fetch/Search, Write |
| Additional Options | Collection of extra settings: - Auto-Execute Plan (for Plan operation): Automatically run simple, low-risk plans - Debug Mode: Enable detailed logging - Plan Detail Level (for Plan operation): High, Detailed, Step-by-Step - Plan Modifications (for Approve Plan): Feedback or changes to apply - Require Permissions: Whether tool usage requires explicit permission - System Prompt: Extra context or instructions for Claude Code |
Output
The node outputs JSON data structured according to the selected output format:
Structured:
An object containing:messages: Array of all exchanged messages (user, assistant, system).summary: Counts of user messages, assistant messages, tool uses, presence of results, and available tools.result: The final result or error message from Claude Code.metrics: Performance data such as duration in milliseconds, number of turns, total cost in USD, and usage statistics.success: Boolean indicating whether the operation succeeded.
Messages:
Raw array of all messages exchanged during the session, including types like user input, assistant responses, and tool uses.Text:
Only the final textual result from Claude Code, typically the generated code or answer.
If the node outputs binary data (not applicable here), it would represent files or other non-textual content generated or manipulated by Claude Code.
For the "Test Project Path" operation, the output includes validation results about the directory existence, permissions, and warnings.
Dependencies
- Requires an API key credential for authenticating with the Claude Code service.
- Uses the official Claude Code SDK (
@anthropic-ai/claude-code) for communication. - Access to the local filesystem to validate and optionally change the working directory for project-related operations.
- Node.js environment with permission to read/write directories if project path is specified.
- n8n environment variables or credentials must be configured to provide the necessary API authentication.
Troubleshooting
Empty Prompt Error:
If the prompt is missing or empty, the node throws an error stating "Prompt is required and cannot be empty." Ensure the prompt field is filled or correctly mapped.Project Path Validation Failures:
When using the "Test Project Path" operation or specifying a project path, errors may occur if:- The directory does not exist.
- The path is not a directory.
- There are no read or write permissions.
The node provides descriptive error or warning messages to guide fixing these issues.
Timeouts:
If Claude Code takes longer than the specified timeout, the operation aborts with a timeout error. Increase the timeout value in additional options if needed.Permission Issues:
If "Require Permissions" is enabled, tool usage may require explicit approval; otherwise, some operations might fail due to insufficient permissions.Working Directory Changes:
Changing the working directory to the specified project path may fail if permissions are inadequate or the path is invalid. The node attempts to restore the original directory after execution.Debugging:
Enable debug mode in additional options to get detailed logs in the n8n console, which helps diagnose issues related to prompts, models, tools, and execution flow.