tmux-worktree-orchestration
┌──────┐ split ┌──────┐ ┌──────┐ ┌──────┐
│ repo │ ════════▶ │🤖 AI │ │🤖 AI │ │🤖 AI │ ⚡ Parallel
└──────┘ └──────┘ └──────┘ └──────┘
│ │ │
merge └───────┴───────┘
▼
┌──────┐
│ ✅ │
└──────┘
A Claude Code Plugin that enables parallel AI-powered development by combining tmux, git worktrees, and multiple Claude Code instances.
🤔 Why This Plugin?
⚡ The Power of AI Concurrent Programming
Traditional development is sequential - you work on one feature, finish it, then move to the next. But with AI coding assistants like Claude Code, we can break this limitation. AI doesn't get tired, doesn't lose context when switching tasks, and can work on multiple problems simultaneously.
This plugin unleashes the full potential of AI-assisted development by allowing you to:
- 🔀 Run multiple Claude Code instances in parallel, each focused on a different feature
- 🚀 Dramatically reduce development time - what used to take days can now be done in hours
- 🔒 Maintain perfect isolation - each feature has its own git branch and working directory, no conflicts
🖥️ Why tmux?
tmux is the perfect companion for AI concurrent programming:
- 💾 Persistent Sessions: SSH disconnected? Computer went to sleep? No problem. tmux sessions keep running. Your Claude Code instances continue working even when you're not connected.
- 🔄 Session Recovery: Simply
tmux attach to reconnect to all your running AI sessions instantly
- 📦 Resource Efficient: Unlike multiple terminal windows, tmux runs in a single process and uses minimal resources
- 🌐 Remote Friendly: Perfect for running on remote servers - start your AI agents, disconnect, come back later to check results
🔧 How It Works
┌─────────────────────────────────────────────────────────────────────────┐
│ Your Development Flow │
└─────────────────────────────────────────────────────────────────────────┘
1. SPLIT: Create parallel development environments
┌──────────────┐
│ Main Repo │ ──── /tmux-worktree-split login signup api ────┐
│ (main) │ │
└──────────────┘ │
▼
┌──────────────────────────────────────────────────────────────────┐
│ tmux session │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Window 1 │ │ Window 2 │ │ Window 3 │ │
│ │ login │ │ signup │ │ api │ │
│ │ ┌─────────┐ │ │ ┌─────────┐ │ │ ┌─────────┐ │ │
│ │ │ Claude │ │ │ │ Claude │ │ │ │ Claude │ │ │
│ │ │ Code │ │ │ │ Code │ │ │ │ Code │ │ │
│ │ └─────────┘ │ │ └─────────┘ │ │ └─────────┘ │ │
│ │ │ │ │ │ │ │
│ │ Worktree: │ │ Worktree: │ │ Worktree: │ │
│ │ repo-login │ │ repo-signup │ │ repo-api │ │
│ │ │ │ │ │ │ │
│ │ Branch: │ │ Branch: │ │ Branch: │ │
│ │feature/login│ │feature/signup│ │ feature/api │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────────────────────────────────────────────────┘
2. DEVELOP: Work on features in parallel (AI does the heavy lifting!)
- Each Claude Code instance works independently
- No conflicts between features
- Switch between windows with Ctrl+b n/p
3. MERGE: Combine everything back
┌──────────────────────────────────────────────────────────────────┐
│ /tmux-worktree-merge │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────┐
│ Main Repo │ ← All features merged, worktrees cleaned up,
│ (main) │ tmux sessions closed, ready for next sprint!
└──────────────┘
📋 State Management
The plugin automatically manages state between split and merge:
-
On Split: Creates .worktree-split-state.md in your project root
- Records base branch, tmux configuration, all feature info
- Copied to each worktree for easy access
-
On Merge: Reads state file and performs cleanup
- Merges all feature branches back to base
- Removes worktrees and cleans up branches
- Kills tmux sessions
- Deletes state file (won't be committed to git)
✨ Features
