Overview
This node integrates with the Claude Code 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, analyze projects, or assist with complex programming workflows by leveraging customizable tool support.
Common scenarios include:
- Generating code snippets or functions based on natural language prompts.
- Automating code review or refactoring suggestions.
- Running multi-turn conversations for complex coding tasks that require iterative refinement.
- Using built-in tools like file editing, web search, or bash commands to interact with a project directory.
Practical example:
- You provide a prompt such as "Create a Python function to parse CSV files," and the node returns generated code along with detailed messages about the conversation.
- For more advanced use, you can enable tools like "Read" and "Write" to allow Claude Code to inspect and modify files in a specified project directory.
Properties
| Name | Meaning |
|---|---|
| Prompt | The instruction or question sent to Claude Code. Supports expressions to dynamically use data from previous nodes. |
| 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 complex or lengthy interactions. |
| Timeout | Maximum time (in seconds) to wait for Claude Code to complete before aborting the operation. |
| Project Path | Directory path where Claude Code should run, allowing it to access files and execute commands within that project. 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, such as Bash commands, file edits, web search, etc. |
| Disallowed Tools | List of built-in tools explicitly blocked from use, taking precedence over allowed tools. |
| Additional Options | Collection of optional settings including: - Debug Mode: Enable detailed logging - Fallback Model: Automatically switch models if primary is overloaded - Max Thinking Tokens: Limits internal reasoning tokens - Permission Mode: How permission requests are handled (default, accept edits automatically, bypass permissions, or planning 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.metrics: Performance data such as duration in milliseconds, number of turns, total cost in USD, and usage statistics.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 only the final result text, success status, duration, and cost. If an error occurs, the result field contains an error message.
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 required beyond standard n8n credential setup.
Troubleshooting
Empty Prompt Error: The node throws an error if the prompt is empty or whitespace. Ensure the prompt property is set and not blank.
Timeouts: If the operation times out (default 300 seconds), increase the timeout value in Additional Options or simplify the prompt.
Maximum Turns Reached: If the maximum conversation turns are reached without completion, consider increasing the
Max Turnsparameter.Execution Errors: Errors during execution are logged if debug mode is enabled. Check logs for details. Common causes include invalid project paths or disallowed tool usage.
Tool Permissions: Misconfiguration of allowed/disallowed tools may prevent Claude Code from performing necessary actions. Review these lists carefully.
Fallback Model: If the primary model is overloaded, enabling a fallback model can improve reliability.