n8n-nodes-tmux-claudecode

cl Simplified Claude Code Project Orchestrator for n8n

Streamlined n8n node for automating development projects with Claude Code integration. Create projects, generate plans, execute them in tmux, and automatically handle Git commits and pull requests.

🔥 v0.3.0 - Simplified Architecture

We've completely redesigned the node to focus on what matters most: seamless Claude Code integration with automated Git workflows.

✨ Core Features

• 🤖 Claude Code Integration: Native plan generation and execution
• 📋 Project Management: Simple project creation and tracking
• ⏰ Smart Scheduling: Queue projects for execution during optimal times
• 🔄 Git Automation: Automatic commits and pull request creation
• 📊 Resource Management: Limit concurrent projects (max 4 per 4-hour window)

🚀 Key Features

🎯 Simplified Workflow

1. Create Project: Define your idea and let Claude Code generate a plan
2. Approve & Execute: Review the plan and execute immediately or schedule for later
3. Auto Git Operations: Automatic commits and PR creation when using Git worktrees
4. Status Monitoring: Track project progress and completion

📋 Project Management

• Prompt-Driven: Simply describe what you want to build
• Dynamic Model Selection: Automatically includes latest Claude models (Sonnet 4, Opus 4.1) with fallback support
• Git Worktree Support: Automatic branch creation and PR management
• Reference Tracking: Optional project references for better organization

⚡ Smart Automation

• Flexible Scheduling: Day/night presets plus custom scheduling
• Smart Project Lookup: Find projects by ID, session name, or reference
• Resource Limits: Prevent system overload with intelligent queuing
• Priority Management: Low/Normal/High priority scheduling
• Session Management: Unique tmux sessions for isolated execution

📦 Installation

Community Node (Recommended)

1. In n8n, go to Settings > Community Nodes
2. Click Install
3. Enter @sirmrmarty/n8n-nodes-tmux-orchestrator
4. Confirm & enjoy!

Prerequisites

• tmux installed on your system
• Claude CLI installed and configured (claude --version should work)
• GitHub CLI (optional, for automatic PR creation): gh --version
• Git configured in your project directories
• Important: If using GitHub, the system will automatically pull the latest version before starting work

🎯 Operations

1. Create Project

Initialize a new project with Claude Code planning:

{
  "operation": "createProject",
  "prompt": "Create a REST API for a todo application with user authentication, CRUD operations, and data persistence using Node.js and PostgreSQL",
  "sessionName": "todo-api-v1",
  "reference": "PROJ-123",
  "projectPath": "/home/user/projects/todo-api",
  "useGitWorktree": true,
  "autoCommit": true,
  "model": "claude-sonnet-4"
}

Response:

{
  "success": true,
  "projectId": "proj_1703123456789_abc123def",
  "sessionName": "todo-api-v1",
  "status": "planned",
  "plan": "Generated plan content...",
  "message": "Project created and plan generated successfully"
}

2. Approve & Execute / Schedule

Execute immediately or schedule for later. You can find projects by ID, session name, or reference:

Execute immediately:

{
  "operation": "approveExecute",
  "projectId": "proj_1703123456789_abc123def",
  "executionMode": "now"
}

Or find by session name:

{
  "operation": "approveExecute",
  "sessionName": "todo-api-v1",
  "executionMode": "now"
}

Schedule with day/night presets:

{
  "operation": "approveExecute",
  "sessionName": "todo-api-v1",
  "executionMode": "schedule",
  "scheduleType": "day",
  "priority": "normal"
}

Schedule for tonight (off-hours):

{
  "operation": "approveExecute",
  "reference": "PROJ-123",
  "executionMode": "schedule",
  "scheduleType": "night",
  "priority": "high"
}

Custom scheduling:

{
  "operation": "approveExecute",
  "projectId": "proj_1703123456789_abc123def",
  "executionMode": "schedule",
  "scheduleType": "custom",
  "scheduleTime": "2024-01-15T14:30:00Z",
  "priority": "normal"
}

Response:

{
  "success": true,
  "projectId": "proj_1703123456789_abc123def",
  "status": "scheduled",
  "scheduledAt": "2024-01-15T09:00:00Z",
  "scheduleType": "day",
  "priority": "normal",
  "message": "Project scheduled successfully for day hours at 9:00 AM: 1/15/2024, 9:00:00 AM"
}

3. Get Status

Monitor project progress and queue status. Find projects by ID, session name, or reference:

Get all projects:

{
  "operation": "getStatus"
}

Get specific project by session name:

{
  "operation": "getStatus",
  "sessionName": "todo-api-v1"
}

Get specific project by reference:

{
  "operation": "getStatus",
  "reference": "PROJ-123"
}

Response:

{
  "success": true,
  "totalProjects": 3,
  "activeProjects": ["proj_123", "proj_456"],
  "projects": [
    {
      "id": "proj_1703123456789_abc123def",
      "sessionName": "todo-api-v1",
      "status": "completed",
      "createdAt": "2024-01-14T10:30:00Z",
      "priority": "normal"
    }
  ]
}

🔧 Configuration Options

Create Project Parameters

• prompt (required): Detailed description of what you want to build
• sessionName (required): Unique identifier for the tmux session
• reference (optional): Project reference number or ticket ID
• projectPath (required): Directory where the project will be created/executed
• useGitWorktree (boolean): Create a new Git worktree branch for the project
• autoCommit (boolean): Automatically commit changes and create PR after execution
• model (options): AI model to use - automatically updated with latest Claude models including Sonnet 4, Opus 4.1, and legacy options

Execution Modes

• Execute Now: Immediate execution (respects resource limits)
• Schedule for Later: Queue for execution with three scheduling options:

Scheduling Options

• Day Hours Preset: Schedule for 9:00 AM (any day including weekends)
  • Avoids night hours (10 PM - 6 AM)
  • Perfect for regular development tasks
• Night Preset: Schedule for 2:00 AM for off-hours processing
  • Ideal for resource-intensive operations
  • Runs during low-activity periods
• Custom Time: Specify exact date and time for execution

Project Lookup Methods

• Project ID: Unique identifier generated during project creation
• Session Name: Human-readable tmux session name
• Reference: Optional project reference or ticket number

Git Integration

• Regular Repos: Commits to current branch with detailed commit message
• Git Worktrees: Creates feature branch, commits, pushes, and creates PR
• Commit Messages: Include project details, model used, and Claude Code attribution

🎮 Example Workflows

Simple Web App Development

{
  "operation": "createProject",
  "prompt": "Build a personal blog website using Next.js with markdown support, responsive design, and dark mode toggle",
  "sessionName": "personal-blog",
  "projectPath": "/home/user/projects/blog",
  "useGitWorktree": false,
  "autoCommit": true,
  "model": "claude-sonnet-4"
}

API Development with PR Workflow

{
  "operation": "createProject",
  "prompt": "Create a GraphQL API for an e-commerce platform with product catalog, user authentication, and order management",
  "sessionName": "ecommerce-graphql",
  "reference": "TICKET-456",
  "projectPath": "/home/user/projects/ecommerce-api",
  "useGitWorktree": true,
  "autoCommit": true,
  "model": "claude-sonnet-4"
}

Scheduled Development with Presets

{
  "operation": "createProject",
  "prompt": "Implement comprehensive test suite for existing Node.js application with unit, integration, and e2e tests",
  "sessionName": "test-suite",
  "reference": "TESTS-789",
  "projectPath": "/home/user/projects/my-app",
  "useGitWorktree": true,
  "autoCommit": true,
  "model": "claude-sonnet-4"
}
// Then schedule using session name and night preset
{
  "operation": "approveExecute",
  "sessionName": "test-suite",
  "executionMode": "schedule",
  "scheduleType": "night",
  "priority": "high"
}
// Or schedule for day hours using reference
{
  "operation": "approveExecute",
  "reference": "TESTS-789",
  "executionMode": "schedule",
  "scheduleType": "day",
  "priority": "normal"
}

🔄 Resource Management

Intelligent Queuing

• Concurrent Limit: Maximum 4 projects executing within any 4-hour window
• Priority Scheduling: High priority projects get preference in the queue
• Time-based Execution: Schedule large projects during off-peak hours

Project Statuses

• created: Project initialized but planning not started
• planning: Claude Code is generating the plan
• planned: Plan ready for review and approval
• executing: Project is currently running in tmux
• completed: Project finished successfully
• failed: Project execution failed
• scheduled: Project queued for future execution

🛠️ Advanced Features

Git Automation

• Smart Commit Messages: Include project context, model used, and references
• Branch Management: Automatic feature branch creation for worktrees
• PR Creation: Uses GitHub CLI to create descriptive pull requests
• Error Handling: Git failures don't crash project execution

Claude Code Integration

• Plan Mode: Uses claude --permission-mode plan for structured project planning
• Execution Mode: Uses claude with model selection for implementing the plan
• Dynamic Model Selection: Automatically includes latest Claude models (Sonnet 4, Opus 4.1)
• Smart Model Options: Proper command-line argument mapping for each model
• Environment Configuration: Optimized model configuration and validation

Session Management

• Isolated Execution: Each project runs in its own tmux session
• Session Naming: Clear, conflict-free session identification
• Path Management: Proper working directory handling
• Cleanup: Automatic session cleanup on completion

🐛 Troubleshooting

Common Issues

Claude CLI Not Found:

# Install Claude CLI
npm install -g @anthropic/claude-cli
# or
pip install claude-cli

# Verify installation
claude --version

Git Operations Failing:

# Check GitHub CLI
gh --version
gh auth status

# Verify Git configuration
git config --global user.name
git config --global user.email

Tmux Session Issues:

# List active sessions
tmux ls

# View session content
tmux capture-pane -t session-name

# Kill stuck session
tmux kill-session -t session-name

Performance Tips

• Use scheduling for large projects to avoid resource conflicts
• Monitor active project count to prevent system overload
• Clean up completed projects regularly
• Use appropriate AI models (Haiku 3.5 for speed, Sonnet 4 for quality, Opus 4.1 for complex tasks)

📖 Best Practices

Project Setup

• Clear Prompts: Provide detailed, specific project descriptions
• Proper Paths: Use absolute paths for project directories
• Git Setup: Ensure Git is properly configured in project directories
• Model Selection: Choose appropriate models for project complexity

Workflow Management

• Scheduling: Use scheduling for resource-intensive projects
• Monitoring: Regularly check project status and queues
• Git Strategy: Use worktrees for team environments, direct commits for personal projects

Error Handling

• Graceful Degradation: Projects continue even if Git operations fail
• Logging: All operations are logged for debugging
• Recovery: Failed projects can be retried with the same configuration

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

📄 License

MIT License - see LICENSE file.

🔗 Links

• n8n Documentation
• Claude AI Documentation
• GitHub Repository
• Report Issues

Ready to automate your development workflow? Install the node and create your first Claude Code project today!