npm package: @jlawman/worktree
Description: CLI tool for managing Git worktrees with GitHub issues and Claude Code integration
Latest version: 1.0.1

# 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

```bash
npm install -g worktree-cli
```

Or clone and link locally:

```bash
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:

```bash
wt init
```

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

### Create/Open Worktree

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

```bash
# Split horizontally (default)
wt split 123

# Split vertically
wt split 123 -v
```

### List Worktrees

```bash
wt list
```

Shows all worktrees with:
- Issue number and branch name
- tmux window status
- Last modified time
- Number of panes

### Remove Worktree

```bash
wt remove 123
# or
wt rm 123
```

Closes tmux window and removes Git worktree.

## Configuration

Edit `.worktree.yml` in your repository:

```yaml
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

```bash
# 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