n8n-nodes-ai-workflow-builder/README.md

AI-powered workflow builder node for n8n using Claude API

# n8n-nodes-ai-workflow-builder

**Native-like AI workflow builder for n8n** using Claude API. Generate, modify, and refine n8n workflows using natural language - similar experience to n8n's built-in AI Workflow Builder.

## Why This Node?

- 🎯 **Native-like Experience**: Chat refinement, validation, and iterative improvements
- 🧠 **Intelligent Context**: Uses only relevant n8n nodes (not all 400+)
- 💰 **Cost-Effective**: Prompt caching reduces costs by ~85%
- 🔧 **Auto-fix**: Automatically validates and fixes common workflow issues
- 💬 **Conversational**: Refine workflows through natural conversation
- 📤 **Flexible Output**: JSON or downloadable file format

## Installation

### Community Nodes (Recommended)

1. Go to **Settings** > **Community Nodes**
2. Select **Install**
3. Enter `n8n-nodes-ai-workflow-builder`
4. Agree to risks and install

### Manual Installation

```bash
npm install n8n-nodes-ai-workflow-builder
```

## Prerequisites

- n8n version 0.187.0 or higher
- Claude API key from [Anthropic](https://console.anthropic.com/)

## Quick Start

### 1. Setup Credentials

1. Get your API key from [Anthropic Console](https://console.anthropic.com/)
2. In n8n: **Credentials** > **New** > **Claude API**
3. Enter your API key
4. Choose model: **Claude Sonnet 4.5** (recommended)

### 2. Add the Node

1. Create a new workflow
2. Add **Manual Trigger** node
3. Add **AI Workflow Builder** node
4. Configure and execute!

## Operations

### 🆕 Generate Workflow

Create a brand new workflow from a natural language description.

**Example:**
```
Create a workflow that sends me a Slack message every morning at 9 AM
with the weather forecast for London
```

**Output:**
- Complete n8n workflow JSON
- Step-by-step import instructions
- Validation results (auto-fixed if needed)
- Token usage and cost breakdown

### 💬 Chat Refinement (NEW!)

**Native-like iterative refinement** - The closest experience to n8n's built-in AI builder!

**How it works:**
1. Generate initial workflow (or start with existing one)
2. Switch to "Chat Refinement" mode
3. Paste previous workflow JSON
4. Send refinement message: "Add error handling"
5. Get updated workflow
6. Continue refining iteratively!

**Example flow:**
```
1st message: "Create a Slack notification workflow"
2nd message: "Add error retry logic"
3rd message: "Make it run every hour"
4th message: "Add logging to a database"
```

Each iteration remembers context and builds on previous changes!

### ✏️ Modify Workflow

One-time modification of an existing workflow.

**Example:**
```
Add error handling to all HTTP Request nodes and send
notifications to Slack on failure
```

### 📖 Explain Workflow

Get a detailed explanation of what a workflow does.

**Great for:**
- Understanding complex workflows
- Documentation
- Onboarding team members
- Identifying issues or improvements

## Comparison to Native n8n AI Builder

| Feature | Native Builder | This Community Node |
|---------|---------------|---------------------|
| **Chat Interface** | Built-in modal | ✅ Chat Refinement mode |
| **Iterative Refinement** | Real-time canvas | ✅ Via conversation history |
| **Workflow Validation** | Automatic | ✅ With auto-fix |
| **Context Awareness** | Full n8n knowledge | ✅ Intelligent context (relevant nodes only) |
| **Direct Canvas Creation** | Yes | ❌ Manual import (community node limitation) |
| **Cost Optimization** | N/A | ✅ 85% savings with prompt caching |
| **Export Options** | Automatic | ✅ JSON + downloadable file |
| **Conversation History** | Built-in | ✅ Manual copy/paste |

## Advanced Features

### Workflow Validation ✅

Automatically checks for:
- Missing trigger nodes
- Invalid node positions
- Missing connections
- Required workflow fields
- Proper node structure

**Auto-fix mode** (enabled by default):
- Adds missing workflow name
- Fixes invalid positions
- Creates connections object
- Ensures all required fields

### Multiple Output Formats 📤

Choose how to receive your workflow:

1. **Workflow JSON**: Copy and import manually
2. **Export File**: Base64 downloadable file
3. **Both**: Get both formats

### Intelligent Context System 🧠

Instead of sending all 400+ n8n nodes to Claude:
1. Extracts keywords from your description
2. Finds 3-10 most relevant keywords
3. Retrieves only relevant nodes (10-15 max)
4. Includes similar workflow examples
5. **Result**: Better quality, lower cost!

**Example:**
- Your request: "Create a Slack notification workflow"
- Keywords extracted: `["slack", "notification", "trigger", "message"]`
- Nodes included: Slack, Webhook, Schedule Trigger, Manual Trigger, Code
- Example shown: "Webhook to Slack" pattern

### Prompt Caching 💰

Massive cost savings through Anthropic's prompt caching:

| Request | Input Tokens | Cached | Cost |
|---------|--------------|--------|------|
| **First** | ~3,300 | 0 | $0.012-$0.015 |
| **Second** | ~100-200 | ~3,200 | $0.002-$0.003 |
| **Third+** | ~100-200 | ~3,200 | $0.002-$0.003 |
| **Savings** | | | **~85%** |

Cache duration: 5 minutes

## Usage Examples

### Example 1: Iterative Chat Refinement

```
Step 1 - Generate:
  "Create a workflow that sends Slack notifications"

Step 2 - Refine (Chat mode):
  Previous Workflow: [paste from step 1]
  Message: "Add error handling with retries"

Step 3 - Refine again:
  Previous Workflow: [paste from step 2]
  Conversation History: [paste from step 2]
  Message: "Make it run every hour"

Step 4 - Final refinement:
  Previous Workflow: [paste from step 3]
  Conversation History: [paste from step 3]
  Message: "Add logging to PostgreSQL"

Result: Fully refined workflow with all features!
```

### Example 2: Daily Report Workflow

**Description:**
```
Create a workflow that runs daily at 8 AM, fetches data from
our PostgreSQL database, generates a summary report, and emails
it to the team at team@company.com
```

**Generated:**
- Schedule Trigger (8 AM daily)
- PostgreSQL query node
- Code node (data formatting)
- Gmail send node

**Validation:** ✅ All checks passed
**Cost:** $0.0128 (first request)
**Time:** ~5 seconds

### Example 3: Customer Support Automation

**Description:**
```
Build a workflow that listens for new Intercom messages,
uses AI to categorize them, and routes urgent issues to
PagerDuty while others go to a Slack channel
```

**Generated:**
- Webhook trigger
- AI Agent (LangChain) for classification
- IF node for routing
- PagerDuty + Slack nodes

**Refinement via Chat:**
```
"Add a cooldown to prevent spam triggering PagerDuty"
```

**Cost:** $0.0024 (cached)

### Example 4: Social Media Monitoring

**Description:**
```
Monitor Twitter for mentions of @ourcompany, analyze sentiment
with AI, and post positive ones to our #social-media Slack channel
```

**Generated:**
- Twitter Trigger (@ourcompany mentions)
- AI sentiment analysis (LangChain)
- IF node (positive sentiment filter)
- Slack post node

## Advanced Options

**Include Examples** (default: on)
- Includes similar workflow patterns
- Helps Claude learn from real examples
- ~500 additional tokens

**Include Node Details** (default: on)
- Adds detailed node documentation
- Relevant nodes only (not all 400+)
- ~2,000 additional tokens

**Temperature** (default: 0.7)
- 0.0 = Deterministic (same input → same output)
- 0.7 = Balanced (recommended)
- 1.0 = Creative (more variation)

**Validate Workflow** (default: on)
- Checks workflow structure
- Identifies issues
- Shows validation results

**Auto-fix Issues** (default: on)
- Automatically fixes common problems
- Adds missing fields
- Corrects positions and connections

## Tips for Best Results

### ✅ DO:
- **Be specific**: Include timing, tools, conditions
- **Name services**: "Slack", "PostgreSQL", not just "database"
- **Describe logic**: "If urgent then X, otherwise Y"
- **Use Chat mode**: For complex workflows, iterate!
- **Check validation**: Review auto-fix suggestions

### ❌ DON'T:
- Be vague: "Make a workflow"
- Skip details: "Send a notification" (to where?)
- Ignore errors: Always review validation results
- Forget credentials: Remember to configure after import

## Pricing

Uses your own Claude API key. See [Anthropic Pricing](https://www.anthropic.com/pricing).

**Typical costs:**
- Simple workflow: $0.01 - $0.05 (first request)
- Simple workflow: $0.002 - $0.003 (cached)
- Complex workflow: $0.05 - $0.20 (first request)
- Modifications: $0.01 - $0.10
- Chat refinement: $0.002 - $0.005 per message (cached)

**Monthly estimates** (based on usage):
- 10 workflows/month: ~$0.20 - $1.00
- 50 workflows/month: ~$1.00 - $5.00
- 200 workflows/month: ~$5.00 - $20.00

*With caching, costs drop by ~85% after first request!*

## Troubleshooting

### "No trigger node found"
The workflow needs a trigger to start execution. Add "trigger" to your description.

### "Invalid workflow JSON"
The AI response couldn't be parsed. Try:
1. Enable "Auto-fix Issues"
2. Regenerate with more specific description
3. Use Chat mode to refine

### "High token usage"
- Disable "Include Node Details" for simpler workflows
- Use shorter descriptions
- Prompt caching helps after first request

### Import errors in n8n
- Check validation results
- Enable "Auto-fix Issues"
- Manually verify node connections
- Configure credentials for nodes that need them

## Architecture

This node uses a sophisticated multi-layer context system:

1. **Core System Prompt** (~800 tokens) - n8n structure basics
2. **Node Database** (variable) - Only relevant nodes
3. **Workflow Examples** (~500 tokens) - Similar patterns
4. **Context Builder** - Intelligent keyword extraction
5. **Prompt Caching** - 85% cost savings

**Total context:** ~3,300 tokens (first request), ~100-200 tokens (cached)

## Support

- 🐛 [Report Issues](https://github.com/hichamchar/perso-n8n-nodes-ai-workflow-builder/issues)
- 💬 [n8n Community](https://community.n8n.io/)
- 📖 [Anthropic Docs](https://docs.anthropic.com/)
- 📘 [n8n Docs](https://docs.n8n.io/)

## Contributing

Contributions welcome! Areas to improve:
- Add more nodes to the database
- Add more workflow examples
- Improve validation logic
- Add more output formats
- Better error handling

## License

MIT

## Author

Hicham Char - [GitHub](https://github.com/hichamchar)

---

**Built with** ❤️ **using Claude Code**