n8n-nodes-claude-code

A community node for n8n that enables Claude Code's autonomous agent capabilities in AI Agent workflows.

Overview

This node integrates Claude Code SDK with n8n's AI Agent infrastructure, giving your workflows access to an autonomous coding agent that can:

• Execute bash commands - Run shell commands, scripts, and system operations
• Read and write files - Create, modify, and analyze files in your project
• Search codebases - Find files by name patterns or search content with regex
• Multi-step reasoning - Complete complex tasks that require multiple tool uses

The node implements a LangChain-compatible chat model interface, making it a drop-in replacement for other language models in n8n's AI Agent node.

Installation

Quick Start

1. In n8n, go to Settings > Community Nodes
2. Enter n8n-nodes-claude-code and click Install
3. Create a Claude Code API credential with your Anthropic API key
4. Add the Claude Code Agent node to an AI Agent workflow

Prerequisites

Before installing this node, ensure you have:

• Self-hosted n8n (v1.0.0 or later) - This node is NOT available on n8n Cloud
• Claude CLI installed globally:

  npm install -g @anthropic-ai/claude-code

• Anthropic API key from console.anthropic.com

Standard n8n Installation

1. Open your n8n instance
2. Navigate to Settings (gear icon in bottom left)
3. Select Community Nodes from the sidebar
4. Click Install a community node
5. Enter n8n-nodes-claude-code in the npm package name field
6. Click Install
7. Restart n8n if prompted

Verify Installation

After installation, search for "Claude Code" in the node panel. You should see the Claude Code Agent node available in the AI > Language Models category.

When running n8n in Docker, the Claude CLI must be installed inside the container. Add the following to your Dockerfile:

FROM n8nio/n8n:latest

# Install Node.js and Claude CLI
USER root
RUN npm install -g @anthropic-ai/claude-code
USER node

Or use a docker-compose override:

services:
  n8n:
    image: n8nio/n8n:latest
    # ... other config
    command: >
      sh -c "npm install -g @anthropic-ai/claude-code && n8n start"

Important: The Claude CLI must be accessible in the container's PATH for the node to function.

Configuration

Credentials

Create a Claude Code API credential with the following options:

| Field | Description | |-------|-------------| | API Key | Your Anthropic API key (starts with sk-ant-api03-). Get one from console.anthropic.com. | | Use CLI Authentication | Toggle this ON if you want to use authentication from a prior claude CLI login. Only works for local installations. Leave API Key empty when using this option. |

Node Options

| Option | Default | Description | |--------|---------|-------------| | Model | Sonnet 4 (Balanced) | The Claude model to use. Options: Sonnet 4 (recommended), Opus 4 (maximum intelligence), Haiku 4 (fast). | | Working Directory | (required) | Absolute path to the directory where the agent operates. The agent can read/write files within this directory. | | System Prompt | (empty) | Custom instructions for the agent. Supports n8n expressions. Leave empty for default agent behavior. | | Max Turns | 10 | Maximum number of conversation turns before the agent returns its partial result. Minimum: 1. |

Usage Examples

The Claude Code Agent node works as a language model within n8n's AI Agent node. Here are some common use cases:

Code Generation

Connect the Claude Code Agent to an AI Agent node and prompt:

"Create a Python script that reads CSV files from the data directory and generates a summary report"

The agent will create the file, write the code, and can even test it.

File Operations

"Read all TypeScript files in the src directory and create a summary of the exported functions"

The agent uses its built-in Glob and Read tools to find and analyze files.

Project Setup

"Initialize a new React component called UserProfile with TypeScript, add unit tests, and update the index exports"

The agent executes multiple steps: creates files, writes code, and modifies existing files.

Code Review

"Review the changes in the utils directory and suggest improvements for error handling"

The agent reads the code and provides detailed analysis.

Limitations and Known Issues

Please be aware of the following limitations before using this node:

Self-hosted Only

This node only works on self-hosted n8n instances. n8n Cloud does not support unverified community nodes that require external CLI tools.

Claude CLI Required

The Claude Code SDK requires the Claude CLI (@anthropic-ai/claude-code) to be installed on the host system. The node spawns the CLI as a subprocess, which means:

• The CLI must be globally installed and in the system PATH
• Docker containers must have the CLI installed inside the container
• Some restricted environments may not allow subprocess spawning

Docker Complexity

Running in Docker requires additional setup to ensure the Claude CLI is accessible. See the Docker Installation section above.

Execution Timeouts

• Long-running agent tasks may hit execution limits depending on your n8n configuration
• Consider setting appropriate maxTurns values for complex tasks
• n8n Cloud has a 100-second webhook timeout (not applicable for self-hosted)

API Costs

Claude API usage incurs costs based on tokens processed. Complex multi-step tasks can consume significant tokens. Monitor your usage at console.anthropic.com.

Troubleshooting

"Claude Code executable not found"

The Claude CLI is not installed or not in PATH.

Solution: Install the CLI globally:

npm install -g @anthropic-ai/claude-code

Verify installation:

which claude
claude --version

"API key invalid" or "Unauthorized"

The API key is missing or incorrect.

Solution:

1. Verify your API key at console.anthropic.com
2. Check that the key is correctly entered in the credential (no extra spaces)
3. Ensure the key has not been revoked

Agent not responding or empty results

Possible causes:

• Max turns reached before completion
• Working directory doesn't exist
• Permission issues in working directory

Solutions:

• Increase maxTurns for complex tasks
• Verify the working directory path exists and is accessible
• Check file permissions in the working directory

Docker: CLI not found in container

Solution: Ensure the CLI is installed in the Docker image. See the Docker Installation section.

Credential test fails but node works

If using CLI authentication, the credential test may fail because it attempts API validation. This is expected - the node will use CLI authentication at runtime.

Contributing

Issues and pull requests are welcome at the GitHub repository.

Before contributing:

• Check existing issues to avoid duplicates
• For feature requests, open an issue first to discuss
• Follow the existing code style

Changelog

See CHANGELOG.md for version history and release notes.

License

MIT - see LICENSE file for details.

Built with the Claude Agent SDK by Anthropic.