@sirmrmarty/n8n-nodes-tmux-orchestrator/README.md

n8n nodes for orchestrating Claude AI agents through tmux sessions

# 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:

```json
{
  "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:**
```json
{
  "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:**
```json
{
  "operation": "approveExecute",
  "projectId": "proj_1703123456789_abc123def",
  "executionMode": "now"
}
```

**Or find by session name:**
```json
{
  "operation": "approveExecute",
  "sessionName": "todo-api-v1",
  "executionMode": "now"
}
```

**Schedule with day/night presets:**
```json
{
  "operation": "approveExecute",
  "sessionName": "todo-api-v1",
  "executionMode": "schedule",
  "scheduleType": "day",
  "priority": "normal"
}
```

**Schedule for tonight (off-hours):**
```json
{
  "operation": "approveExecute",
  "reference": "PROJ-123",
  "executionMode": "schedule",
  "scheduleType": "night",
  "priority": "high"
}
```

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

**Response:**
```json
{
  "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:**
```json
{
  "operation": "getStatus"
}
```

**Get specific project by session name:**
```json
{
  "operation": "getStatus",
  "sessionName": "todo-api-v1"
}
```

**Get specific project by reference:**
```json
{
  "operation": "getStatus",
  "reference": "PROJ-123"
}
```

**Response:**
```json
{
  "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
```json
{
  "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
```json
{
  "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
```json
{
  "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:**
```bash
# Install Claude CLI
npm install -g @anthropic/claude-cli
# or
pip install claude-cli

# Verify installation
claude --version
```

**Git Operations Failing:**
```bash
# Check GitHub CLI
gh --version
gh auth status

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

**Tmux Session Issues:**
```bash
# 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](LICENSE) file.

## 🔗 Links

- [n8n Documentation](https://docs.n8n.io)
- [Claude AI Documentation](https://claude.ai)
- [GitHub Repository](https://github.com/sirmrmarty/n8n-nodes-tmux-claudecode)
- [Report Issues](https://github.com/sirmrmarty/n8n-nodes-tmux-claudecode/issues)

---

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