tomevault-io Git Worktrees with tmux Integration
Create isolated workspaces, open them in tmux windows within your current session, and dispatch tasks — all in one flow.
Core Flow
1. Create worktree → git worktree add .claude/worktrees/{name} -b {branch}
2. Create tmux window → new window in CURRENT session named {session}-{name}
3. cd into worktree → send-keys to the new window
4. Dispatch task → send-keys with the command to execute
Workflow Routing
| Intent | Action |
|---|---|
| "create worktree for X" | Create → steps 1-3 only |
| "create worktree and run Y" | Create + Dispatch → steps 1-4 |
| "clean up worktree X" | Cleanup → remove worktree + tmux window + optionally delete branch |
| "list worktrees" | Show git worktree list |
| "analyze for parallelization" | Read references/bmad-orchestration.md for BMAD-specific dependency analysis |
| "merge worktree branches" | Read references/bmad-orchestration.md for merge workflow |
Step 1: Create Worktree
Safety Check
Before creating, verify .claude/worktrees/ is git-ignored:
# Check if ignored (test with a hypothetical file)
git check-ignore .claude/worktrees/test 2>/dev/null
If NOT ignored, add to .gitignore immediately:
echo ".claude/worktrees/" >> .gitignore
# Stage and commit the gitignore change
Create
REPO_ROOT=$(git rev-parse --show-toplevel)
WORKTREE_NAME="the-feature-name"
BRANCH_NAME="feature/the-feature-name" # or bmad/story-1-3 etc.
BASE_BRANCH="main" # or current branch
mkdir -p "$REPO_ROOT/.claude/worktrees"
git worktree add "$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME" -b "$BRANCH_NAME" "$BASE_BRANCH"
Verify
git worktree list
Step 2: Create tmux Window
Create a new window in the current tmux session (not a new session). The window name follows the pattern {current-session-name}-{worktree-name} so it's easy to identify.
# Get current tmux session name
SESSION=$(tmux display-message -p '#S')
WINDOW_NAME="${SESSION}-${WORKTREE_NAME}"
WORKTREE_PATH="$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME"
# Create window in current session, starting in worktree directory
tmux new-window -t "$SESSION" -n "$WINDOW_NAME" -c "$WORKTREE_PATH"
Step 3: Ensure Working Directory
The -c flag in step 2 already sets the initial directory, but if you need to explicitly cd (e.g., shell profile overrides it):
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "cd '$WORKTREE_PATH'" Enter
Step 4: Dispatch Task (Optional)
Send a command to the new tmux window:
# Example: launch Claude Code with a task
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude 'your task here'" Enter
# Example: run a BMAD skill
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude '/bmad-create-story story 1-3'" Enter
# Example: run any shell command
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "make test" Enter
For unattended execution (no permission prompts):
tmux send-keys -t "${SESSION}:${WINDOW_NAME}" "claude --dangerously-skip-permissions 'your task'" Enter
Important: Only use --dangerously-skip-permissions if the user explicitly requests it.
Cleanup Workflow
After work is complete and merged:
WORKTREE_NAME="the-feature-name"
REPO_ROOT=$(git rev-parse --show-toplevel)
SESSION=$(tmux display-message -p '#S')
# 1. Kill the tmux window
tmux kill-window -t "${SESSION}:${SESSION}-${WORKTREE_NAME}" 2>/dev/null
# 2. Remove the git worktree
git worktree remove "$REPO_ROOT/.claude/worktrees/$WORKTREE_NAME"
# 3. Optionally delete the branch (only if merged)
git branch -d "$BRANCH_NAME" 2>/dev/null
# 4. Prune stale worktree references
git worktree prune
Quick Reference
| Situation | Action |
|---|---|
.claude/worktrees/ exists |
Use it (verify ignored) |
Not in .gitignore |
Add .claude/worktrees/ and commit |
| Not in tmux | Skip tmux steps, just create worktree and report path |
| Branch already exists | Use git worktree add <path> <existing-branch> (no -b) |
| Worktree path exists | Report error, ask user to remove or pick different name |
Naming Conventions
| Element | Pattern | Example |
|---|---|---|
| Worktree directory | .claude/worktrees/{name} |
.claude/worktrees/story-1-3 |
| Branch | {convention}/{name} |
bmad/story-1-3-deploy-nat-gateway |
| tmux window | {session}-{name} |
hypera-golden-image-story-1-3 |
The branch naming convention depends on the project. Check CLAUDE.md for project-specific patterns (e.g., bmad/story-{id} for BMAD projects).
Troubleshooting
Branch already checked out:
# Another worktree has this branch — remove it first or use a different name
git worktree list # find which worktree has the branch
tmux window name conflict:
# Rename or kill the conflicting window
tmux kill-window -t "session:conflicting-name" 2>/dev/null
Worktree not in .gitignore after adding:
# .gitignore uses directory patterns — ensure trailing slash
# Check with: git check-ignore .claude/worktrees/testfile
References
- WORKFLOW.md — Detailed step-by-step workflow with edge cases
- references/bmad-orchestration.md — BMAD sprint parallelization, dependency analysis, and merge workflows
- references/tmux-integration.md — Advanced tmux configuration for worktrees
- scripts/setup-worktree.sh — Shell script for automated worktree setup
Converted and distributed by TomeVault — claim your Tome and manage your conversions.