# Worktree Beads Tmux Orchestrator

> This skill should be used when the user wants to set up, manage, or optimize a development workflow combining Git worktrees, Beads task management, and Tmux session management. Triggers on phrases like "setup worktree workflow", "manage multiple branches", "parallel development", "beads task tracking", "tmux session for project", "context switching", "hotfix while coding", "organize development environment", or any discussion of development workflow optimization, task management with beads, terminal session management, or git worktree usage. Provides automated scenario detection and recommended workflow patterns.

- Skill: `bowtiedswan/worktree-beads-tmux-orchestrator` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add bowtiedswan/worktree-beads-tmux-orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bowtiedswan/worktree-beads-tmux-orchestrator/raw
- Safety review: WARNING
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: bowtiedswan (https://skillmd.com/u/bowtiedswan)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bowtiedswan/worktree-beads-tmux-orchestrator

---


# Worktree-Beads-Tmux Orchestrator

## Overview

This skill orchestrates a professional-grade development workflow by combining four powerful tools:
- **Git Worktrees**: Parallel development environments without context loss
- **Beads**: Git-backed graph task tracker for AI agents
- **Beads Viewer (bv)**: TUI and analysis engine for task visualization
- **Tmux**: Persistent terminal sessions that survive disconnects

The skill automatically identifies the user's scenario and recommends optimal workflow patterns.

## Workflow Decision Tree

```
User Request
    │
    ├─► "Setup new project workflow" ───────► Setup Workflow
    │
    ├─► "Switch to different task" ─────────► Context Switch Pattern
    │
    ├─► "Working on multiple features" ─────► Parallel Development Pattern
    │
    ├─► "Hotfix needed" ────────────────────► Interrupt Response Pattern
    │
    ├─► "Organize my terminal" ─────────────► Tmux Session Pattern
    │
    ├─► "Track tasks/Create task" ──────────► Beads Task Management
    │
    ├─► "View tasks/What's next" ───────────► Beads Analysis
    │
    └─► "Review PR/Check branch" ───────────► Review Workflow Pattern
```

## Scenario Detection

### Pattern 1: Long-Running Feature Development
**Signals**: "Working on epic", "big refactor", "feature will take weeks"
**Approach**:
1. Create dedicated worktree: `git worktree add ../feature-name -b feature/name`
2. Initialize beads: `bd init`
3. Break down with beads: Create epic → tasks → subtasks
4. Setup tmux session: `tmux new-session -d -s feature-name`
5. Daily: Use `bv --robot-plan` for parallel execution tracks

### Pattern 2: Interrupt-Driven Development
**Signals**: "Need to fix bug", "hotfix", "urgent issue", "interrupt"
**Approach**:
1. Check if hotfix worktree exists: `git worktree list`
2. If not: `git worktree add ../hotfix-{issue} main`
3. Switch to hotfix: `cd ../hotfix-{issue}`
4. No stash/checkout/pop needed - zero context loss
5. Fix, commit, push, return to original worktree

### Pattern 3: Multi-Branch Code Review
**Signals**: "Review PR", "check someone's branch", "review code"
**Approach**:
1. Create temporary worktree: `git worktree add --detach ../pr-{number}`
2. Fetch PR: `git fetch origin pull/{number}/head:pr-{number}`
3. Checkout: `git checkout pr-{number}`
4. Review in tmux window: `tmux new-window -n pr-{number}`
5. Delete when done: `rm -rf ../pr-{number} && git worktree prune`

### Pattern 4: Terminal Organization
**Signals**: "Organize terminal", "persistent session", "disconnected", "SSH"
**Approach**:
1. Create tmux session: `tmux new-session -d -s {project}`
2. Setup windows: editor, beads, terminal, logs
3. Start bv in beads window
4. Attach: `tmux attach -t {project}`
5. Detach with `Ctrl+b d` - session persists

### Pattern 5: Task Management & Planning
**Signals**: "Create task", "track issue", "what to work on", "prioritize"
**Approach**:
1. Human mode: Run `bv` for TUI
2. AI mode: Run `bv --robot-triage` for JSON analysis
3. Create: `bd create "Title" -p 0`
4. Claim: `bd update {id} --claim`
5. Check dependencies: `bv --robot-insights | jq '.CriticalPath'`

## Core Capabilities

### 1. Automated Workflow Setup

For new projects, execute setup sequence:

```bash
#!/bin/bash
# setup-workflow.sh - Generated by this skill

PROJECT_NAME=$1
REPO_URL=$2

# Create directory structure
mkdir -p ~/worktrees/${PROJECT_NAME}
cd ~/worktrees/${PROJECT_NAME}

# Clone as bare repo
git clone --bare ${REPO_URL} .git
cd .git

# Create main worktree
git worktree add ../main

# Initialize beads
cd ../main
bd init

# Create AGENTS.md entry
cat >> AGENTS.md << 'EOF'
## Workflow Tools

This project uses worktree-beads-tmux workflow:
- `bd ready` - List available tasks
- `bv --robot-triage` - AI task analysis
- `git worktree list` - Show worktrees
- `tmux attach -t {project}` - Attach to session
EOF

# Setup tmux session
tmux new-session -d -s ${PROJECT_NAME} -c ~/worktrees/${PROJECT_NAME}/main
tmux new-window -t ${PROJECT_NAME}:2 -n beads
tmux send-keys -t ${PROJECT_NAME}:2 "bv" Enter

echo "Setup complete! Attach with: tmux attach -t ${PROJECT_NAME}"
```

### 2. Context Switch Helper

When user needs to switch contexts:

```bash
# List all worktrees with their beads status
for dir in ~/worktrees/${PROJECT}/*/; do
  if [ -d "$dir/.beads" ]; then
    echo "Worktree: $dir"
    (cd "$dir" && bd ready 2>/dev/null | head -5)
    echo "---"
  fi
done
```

### 3. Smart Tmux Session Management

```bash
# Check if session exists, create if not
if ! tmux has-session -t ${PROJECT} 2>/dev/null; then
  tmux new-session -d -s ${PROJECT} -c ${WORKDIR}
  tmux new-window -t ${PROJECT}:2 -n beads -c ${WORKDIR}
  tmux new-window -t ${PROJECT}:3 -n logs -c ${WORKDIR}
fi
tmux attach -t ${PROJECT}
```

### 4. Beads Integration Commands

**Human Workflow**:
```bash
bv                          # Launch TUI
# Press 'r' for ready tasks
# Press 'i' for insights
# Press 'g' for graph view
```

**AI Agent Workflow**:
```bash
# Always use --robot-* flags in agent context
bv --robot-triage                    # Full analysis
bv --robot-next                      # Top pick only
bv --robot-plan                      # Parallel execution tracks
bv --robot-insights                  # Graph metrics
bv --robot-diff --diff-since HEAD~7  # Recent changes
```

## Quick Reference

### Git Worktree Commands

| Command | Purpose |
|---------|---------|
| `git worktree add <path> <branch>` | Create new worktree |
| `git worktree add -b <new-branch> <path>` | Create worktree + branch |
| `git worktree list` | List all worktrees |
| `git worktree prune` | Clean up stale entries |
| `rm -rf <path>` | Remove worktree (then prune) |

### Beads Commands

| Command | Purpose |
|---------|---------|
| `bd init` | Initialize beads |
| `bd ready` | List unblocked tasks |
| `bd create "Title" -p 0` | Create P0 task |
| `bd show <id>` | Show task details |
| `bd update <id> --claim` | Claim task |
| `bd dep add <child> <parent>` | Add dependency |
| `bd sync` | Sync with remote |

### Beads Viewer Commands

| Command | Purpose |
|---------|---------|
| `bv` | Launch TUI (human only) |
| `bv --robot-triage` | Full analysis (AI) |
| `bv --robot-next` | Top pick (AI) |
| `bv --robot-plan` | Execution plan (AI) |
| `bv --robot-insights` | Graph metrics (AI) |

### Tmux Commands

| Command | Purpose |
|---------|---------|
| `tmux new-session -s name` | New session |
| `tmux attach -t name` | Attach to session |
| `tmux ls` | List sessions |
| `Ctrl+b d` | Detach |
| `Ctrl+b c` | New window |
| `Ctrl+b %` | Split vertical |
| `Ctrl+b "` | Split horizontal |

## Installation

### One-Time System Setup

```bash
# Install beads
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

# Install beads viewer
brew install dicklesworthstone/tap/bv

# Install tmux
brew install tmux  # macOS
sudo apt-get install tmux  # Ubuntu/Debian

# Verify git version (need 2.5+)
git --version
```

### Per-Project Setup

```bash
# In your project directory
cd ~/projects/my-project

# Initialize beads
bd init

# Create tmux session
tmux new-session -d -s my-project
tmux new-window -t my-project:2 -n beads
tmux send-keys -t my-project:2 "cd ~/projects/my-project && bv" Enter

# Add to AGENTS.md
echo "Use 'bd' for task tracking. See 'bv --robot-triage' for planning." >> AGENTS.md
```

## Common Patterns

### Pattern: Daily Standup Prep

```bash
# Get project health
bv --robot-insights | jq -r '.quick_ref'

# See what changed
bv --robot-diff --diff-since yesterday

# Check blockers
bv --robot-insights | jq '.Blockers'
```

### Pattern: Sprint Planning

```bash
# Get parallel execution tracks
bv --robot-plan

# Identify critical path
bv --robot-insights | jq '.CriticalPath'

# Find cycles (must fix!)
bv --robot-insights | jq '.Cycles'
```

### Pattern: End-of-Day Sync

```bash
# Sync beads
bd sync

# Export current state
bv --export-md ~/beads-reports/$(date +%Y-%m-%d).md

# Detach tmux session
Ctrl+b d
```

## Troubleshooting

### Worktree Issues

**Problem**: Worktree already exists error
```bash
# Remove stale worktree reference
git worktree prune -v

# Or force remove
git worktree remove <path> --force
```

**Problem**: Permission denied when removing worktree
```bash
# Manually remove then prune
rm -rf <path>
git worktree prune
```

### Beads Issues

**Problem**: bd command not found
```bash
# Add to PATH
export PATH="$HOME/.beads/bin:$PATH"

# Or reinstall
curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
```

**Problem**: bv TUI not displaying correctly
```bash
# Check terminal supports Unicode
echo -e '\u2500\u2502\u250c\u2510'

# Use ASCII mode if needed
bv --ascii
```

### Tmux Issues

**Problem**: Session already exists
```bash
# Attach to existing
tmux attach -t session-name

# Or kill and recreate
tmux kill-session -t session-name
tmux new-session -d -s session-name
```

**Problem**: Tmux key bindings not working
```bash
# Check prefix key
tmux list-keys | grep prefix

# Common prefixes: Ctrl+b (default), Ctrl+a (custom)
```

## Best Practices

### Worktree Organization

```
~/worktrees/
├── project-a/
│   ├── .git/          # Bare repo
│   ├── main/          # main branch
│   ├── feature-auth/  # feature branch
│   └── hotfix-bug/    # hotfix branch
└── project-b/
    ├── .git/
    ├── main/
    └── experiment/
```

### Tmux Session Naming

- Use project names: `{project}` for main
- Use descriptive names: `{project}-{feature}` for features
- Use temporary names: `pr-{number}` for PR reviews

### Beads Workflow Integration

1. Always claim tasks before working: `bd update <id> --claim`
2. Use robot mode in agent contexts: `bv --robot-*`
3. Check for cycles regularly: `bv --robot-insights | jq '.Cycles'`
4. Sync at end of day: `bd sync`

## Resources

- **Beads**: https://github.com/steveyegge/beads
- **Beads Viewer**: https://github.com/Dicklesworthstone/beads_viewer
- **Git Worktrees**: https://git-scm.com/docs/git-worktree
- **Tmux**: https://github.com/tmux/tmux/wiki

## References

See `references/` directory for:
- `workflow-guide.md` - Comprehensive workflow documentation
- `commands-reference.md` - Full command reference
- `scenario-patterns.md` - Common patterns by scenario