Overview
This node integrates with the Claude Code SDK to perform AI-powered coding tasks through conversational interactions. It allows users to start new conversations or continue previous ones with Claude Code, an AI assistant specialized in code generation, editing, and project management. The node supports customizable tool usage during execution, enabling complex workflows such as running shell commands, editing files, searching web content, and managing todo lists.
Typical use cases include:
- Generating code snippets or functions based on natural language prompts.
- Continuing a coding conversation to refine or extend previously generated code.
- Automating project-related tasks by allowing Claude Code to interact with files and external resources.
- Using AI assistance for debugging, documentation, or code review within a specified project directory.
For example, a user might prompt Claude Code to "Create a Python function to parse CSV files" and receive structured output including the generated code and related messages. Alternatively, continuing a conversation can help iteratively improve or debug the code.
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. Increase for more complex or longer interactions. |
| Timeout | Maximum time (in seconds) to wait for the operation to complete before aborting. |
| Project Path | Directory path where Claude Code should run, allowing it to access files and execute commands in 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 | List of built-in tools Claude Code is permitted to use during execution. Examples include Bash commands, file edits, web search, todo list management, etc. |
| Disallowed Tools | List of built-in tools explicitly blocked from use. Takes precedence over Allowed Tools. |
| Additional Options | Collection of optional settings: - Debug Mode: Enable detailed logging - Fallback Model: Automatically switch models if primary is overloaded - Max Thinking Tokens: Limit tokens for internal reasoning - Permission Mode: How permission requests are handled (default, accept edits, bypass, plan mode) - 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 messages exchanged during the conversation (user, assistant, system).summary: Counts of user messages, assistant messages, tool uses, and whether a final result exists.result: The final output text or error message from Claude Code.metrics: Performance and cost metrics such as duration in milliseconds, number of turns, total cost in USD, and token usage.success: Boolean indicating if the operation completed successfully.
Messages:
A raw array of all messages exchanged plus a count of total messages.Text:
A simplified object containing:result: The final textual output or error message.success: Whether the operation succeeded.duration_ms: Execution time in milliseconds.total_cost_usd: Cost incurred for the operation.
If the node encounters errors or timeouts, the output includes error details accordingly.
The node does not output binary data.
Dependencies
- Requires an API key credential for authenticating with the Claude Code service.
- Uses the official Claude Code SDK (
@anthropic-ai/claude-code) to communicate with the AI backend. - No additional environment variables are explicitly required beyond standard n8n credential setup.
- Network connectivity to the Claude Code API endpoint is necessary.
Troubleshooting
Empty Prompt Error: The node throws an error if the prompt is empty or only whitespace. Ensure the prompt parameter is set and contains meaningful instructions.
Timeouts: If the operation exceeds the configured timeout, an abort error occurs. Increase the timeout value in seconds under Additional Options if needed.
Maximum Turns Reached: When the conversation reaches the maximum allowed turns without completing, the node returns a partial result with a note suggesting increasing the
maxTurnsparameter.Execution Errors: Errors during Claude Code execution (e.g., internal failures) are logged and surfaced in the output. Enabling Debug Mode helps diagnose issues by providing detailed logs.
Tool Permissions: Misconfiguration of allowed/disallowed tools may cause unexpected behavior. Disallowed tools take precedence and block usage even if also listed as allowed.
Fallback Model Usage: If the primary model is overloaded, the node can automatically switch to a fallback model if configured. Otherwise, requests may fail or be delayed.
Debug Logs: Enable Debug Mode to get detailed step-by-step logs of the interaction, including message types, content previews, and timing information.