Overview
The "Claude Code" node integrates with the Claude Code SDK to perform AI-powered coding tasks through conversational interactions. It supports multiple operations such as continuing a conversation, creating plans for coding tasks, approving and executing plans, querying new instructions, and testing project directory paths.
This node is beneficial in scenarios where developers want to automate or assist software development workflows using AI, including generating code snippets, planning complex coding tasks, managing project files, and interacting with codebases programmatically. For example, you can use it to:
- Continue an ongoing coding conversation with Claude Code to refine or extend code.
- Create detailed step-by-step plans for implementing features or refactoring code.
- Approve and execute previously generated plans with optional modifications.
- Validate that a specified project directory exists and has proper permissions before running code generation or editing tasks.
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 to use: - 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 the operation to complete before aborting. |
| Project Path | Directory path where Claude Code should run, allowing access to files and commands within that project. If empty, uses the current working directory. |
| Output Format | Determines how the output data is formatted: - Structured: Object containing messages, summary, result, and metrics - Messages: Raw array of all exchanged messages - Text: Only 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 after creation - Debug Mode: Enable debug logging - Plan Detail Level (for Plan operation): High Level, Detailed, Step-by-Step - Plan Modifications (for Approve Plan operation): Feedback or changes to apply before execution - Require Permissions: Whether tool use requires explicit permission - System Prompt: Additional 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 or error message from Claude Code.metrics: Performance and usage data such as duration in milliseconds, number of turns, total cost, and usage details.success: Boolean indicating if the operation succeeded.
Messages: Raw array of all messages exchanged, including user inputs, assistant responses, tool invocations, system messages, and results.
Text: Only the final result text or error string from the last assistant message.
If the node outputs binary data (not applicable here), it would represent files or other non-textual content generated or manipulated by Claude Code.
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 via Node.js
fsandpathmodules to validate and set the working directory. - n8n environment must allow setting working directories and have appropriate permissions for file operations if a project path is specified.
Troubleshooting
Empty Prompt Error: The prompt input is required and cannot be empty. Ensure the "Prompt" property is filled with valid instructions.
Project Path Validation Errors: When using the "Test Project Path" operation or specifying a project path:
- Directory does not exist: Create the directory or correct the path.
- Path is not a directory: Specify a valid directory path.
- No read permission: Adjust directory permissions to allow reading.
- No write permission: Warning that Claude Code may not be able to create or modify files; adjust permissions if needed.
Timeouts: If the operation times out, consider increasing the "Timeout" value in seconds.
Permission Issues: If "Require Permissions" is enabled, ensure that necessary permissions are granted for tool usage.
Working Directory Changes: The node temporarily changes the working directory to the specified project path during execution and restores it afterward. Failures in changing directories may cause errors.
Debugging: Enable "Debug Mode" in additional options to get detailed logs in the n8n console for troubleshooting.