Overview
The node integrates with the Claude Code AI SDK to assist users in generating, planning, and executing coding tasks through conversational AI. It supports creating detailed plans for programming tasks, continuing conversations, approving and executing plans, querying the AI for code-related assistance, and validating project directory paths.
Typical use cases include:
- Generating step-by-step or high-level plans for software development tasks.
- Automating code generation or modification based on user prompts.
- Managing multi-turn conversations with the AI to refine code or plans.
- Validating project directories before running code generation or execution.
- Controlling which built-in tools the AI can use during task execution (e.g., file editing, web search).
Example: A developer could input a prompt like "Create a Python function to parse CSV files" and receive a detailed plan outlining the steps, including reading the file, parsing logic, error handling, and testing. They can then approve and execute this plan automatically or manually.
Properties
| Name | Meaning |
|---|---|
| Prompt | The instruction or query sent to Claude Code. Supports expressions to dynamically use data from previous nodes. |
| 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 exchanges allowed with Claude Code. |
| Timeout | Maximum time in seconds to wait for the AI response before aborting the operation. |
| Project Path | Directory path where Claude Code runs, allowing access to project files and commands. If empty, uses current working directory. |
| Output Format | Format of the output data: • Structured — Object with 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 — Automatically run simple, low-risk plans after creation • Debug Mode — Enable debug logging • Plan Detail Level — High level, Detailed, or Step-by-Step • Plan Modifications — Feedback to modify approved plans • Require Permissions — Whether tool use 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 message objects exchanged during the session.summary: Counts of user messages, assistant messages, tool uses, presence of results, and available tools.result: The final result text or error message.metrics: Performance data such as duration in milliseconds, number of turns, total cost in USD, and usage statistics.success: Boolean indicating if the operation succeeded.
Messages: Raw array of all messages exchanged, including user inputs, assistant responses, and tool uses.
Text: Only the final result text string from the AI.
If the node handles binary data (not indicated here), it would summarize its meaning accordingly; however, this node focuses on textual and structured JSON outputs.
Dependencies
- Requires an API key credential for authenticating with the Claude Code AI service.
- Uses the Claude Code SDK (
@anthropic-ai/claude-code) for communication with the AI. - Access to the local filesystem for project path validation and setting the working directory.
- Node.js environment with permissions to read/write specified project directories.
- n8n environment configured to allow setting timeouts and managing abort signals for long-running operations.
Troubleshooting
Empty Prompt Error: The node throws an error if the prompt is missing or empty. Ensure the "Prompt" property is set and not blank.
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.
- The node lacks read or write permissions.
Verify the path exists, is a directory, and has appropriate permissions.
Timeouts: If the operation times out, consider increasing the "Timeout" value in seconds. The node will throw a timeout error if the AI does not respond within this period.
Permission Issues: If "Require Permissions" is enabled, ensure that necessary permissions are granted for tool usage; otherwise, the node may fail when the AI attempts to use restricted tools.
Working Directory Changes: The node temporarily changes the process working directory to the specified project path. Errors restoring the original directory are logged but do not stop execution. Ensure the environment allows directory changes.
Debugging: Enable "Debug Mode" to get detailed logs about execution flow, prompts, tool usage, and system context, which helps diagnose issues.
Links and References
- Claude Code SDK Documentation (for understanding the underlying AI integration)
- n8n Node Development Guide (for general custom node development concepts)
- Node.js fs module (for filesystem operations used in project path validation)
- Node.js process.chdir() (for changing working directories)