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:

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

# 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

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

bv                          # Launch TUI
# Press 'r' for ready tasks
# Press 'i' for insights
# Press 'g' for graph view

AI Agent Workflow:

# 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

# 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

# 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

# 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

# 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

# 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

# Remove stale worktree reference
git worktree prune -v

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

Problem: Permission denied when removing worktree

# Manually remove then prune
rm -rf <path>
git worktree prune

Beads Issues

Problem: bd command not found

# 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

# Check terminal supports Unicode
echo -e '\u2500\u2502\u250c\u2510'

# Use ASCII mode if needed
bv --ascii

Tmux Issues

Problem: Session already exists

# 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

# 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