Worktree CLI

A powerful CLI tool for managing Git worktrees with GitHub issues and Claude Code integration. Create isolated workspaces for each issue with automatic context loading and tmux session management.

Features

• 🌳 Git Worktree Management - Create isolated branches and directories per issue
• 🐙 GitHub Integration - Fetch issue details automatically
• 🤖 Claude Code Integration - Auto-launch Claude with issue context
• 🖥️ tmux Session Management - Organized windows and panes per issue
• 📝 Contextual Documentation - Auto-generated CLAUDE.md with project info
• ⚡ Smart Commands - Quick access to development commands

Prerequisites

• Git
• tmux
• iTerm2 (macOS)
• GitHub CLI (gh) - Install with brew install gh
• Claude Code CLI (claude)

Installation

npm install -g worktree-cli

Or clone and link locally:

git clone https://github.com/yourusername/worktree-cli
cd worktree-cli
npm install
npm run build
npm link

Usage

Initialize Configuration

In your Git repository:

wt init

This creates .worktree.yml with auto-detected project settings.

Create/Open Worktree

# Create worktree for issue #123
wt open 123

# With description for better branch naming
wt open 123 "add-authentication"
# Creates branch: issue-123-add-authentication

Split Pane

When you need multiple Claude instances for the same issue:

# Split horizontally (default)
wt split 123

# Split vertically
wt split 123 -v

List Worktrees

wt list

Shows all worktrees with:

• Issue number and branch name
• tmux window status
• Last modified time
• Number of panes

Remove Worktree

wt remove 123
# or
wt rm 123

Closes tmux window and removes Git worktree.

Configuration

Edit .worktree.yml in your repository:

name: "My Project"
session: "myproject_workers"
claude_context: |
  This is a Next.js app with TypeScript.
  Key areas:
  - src/app - App router pages
  - src/lib - Utilities and actions
  
commands:
  dev: npm run dev
  test: npm test
  lint: npm run lint
  typecheck: npm run typecheck
  
setup_commands:
  - npm install

How It Works

1. Creates Git worktree - Isolated directory with new branch
2. Fetches GitHub issue - Gets title, body, labels via gh CLI
3. Generates CLAUDE.md - Combines issue details with project context
4. Launches Claude Code - In tmux window/pane with working directory set
5. Auto-sends command - After 5 seconds, sends "Solve the issue described in CLAUDE.md"

tmux Commands

• List windows: Ctrl+B, w
• Switch window: Ctrl+B, [0-9]
• Detach session: Ctrl+B, d
• Reattach: tmux attach -t <session-name>

Example Workflow

# Start working on issue #42
wt open 42 "fix-login-bug"

# Claude opens and starts working...
# Need to check something else? Split the pane
wt split 42

# See all your worktrees
wt list

# Done with the issue?
wt rm 42

Tips

• Run wt init in each repository to customize settings
• Use descriptive names with wt open for better branch names
• Multiple Claude instances can work on different aspects of the same issue
• The CLAUDE.md file is automatically added to .gitignore

License

MIT