Metadata-Version: 2.4
Name: claude-worktree
Version: 0.9.5
Summary: CLI tool integrating git worktree with Claude Code for seamless feature development workflows
Project-URL: Homepage, https://github.com/DaveDev42/claude-worktree
Project-URL: Repository, https://github.com/DaveDev42/claude-worktree
Project-URL: Issues, https://github.com/DaveDev42/claude-worktree/issues
Author-email: Dave <dave.dev@icloud.com>
License: BSD-3-Clause
License-File: LICENSE
Keywords: claude,cli,development,git,workflow,worktree
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Version Control :: Git
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: packaging>=24.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

# Claude Worktree

> Seamlessly integrate git worktree with Claude Code for streamlined feature development workflows

[![Tests](https://github.com/DaveDev42/claude-worktree/workflows/Tests/badge.svg)](https://github.com/DaveDev42/claude-worktree/actions)
[![PyPI version](https://badge.fury.io/py/claude-worktree.svg)](https://pypi.org/project/claude-worktree/)
[![Python versions](https://img.shields.io/pypi/pyversions/claude-worktree.svg)](https://pypi.org/project/claude-worktree/)
[![License: BSD-3-Clause](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)

## What is Claude Worktree?

**claude-worktree** (or `cw` for short) is a CLI tool that makes it effortless to work on multiple git branches simultaneously using git worktrees, with automatic AI coding assistant integration. No more branch switching, stashing changes, or losing context—each feature gets its own directory and AI session.

Works with Claude Code, Codex, Happy, and any custom AI tool.

### Key Features

- 🌳 **Easy Worktree Management**: Create isolated directories for each feature branch
- 🤖 **Multi-AI Support**: Works with Claude Code, Codex, Happy, and custom AI tools
- 🔄 **Clean Merge Workflow**: Rebase, merge, and cleanup with a single command
- 🔧 **Health Monitoring**: Check worktree health, detect stale branches, and get recommendations
- 📊 **Analytics & Visualization**: View statistics, tree hierarchy, and compare branches
- 🎯 **AI-Assisted Workflows**: Get AI help with conflict resolution during merges
- 📦 **Template System**: Save and reuse worktree setups across projects
- 💾 **Smart Stash Management**: Organize stashes by worktree for easy context switching
- 🧹 **Batch Cleanup**: Clean up multiple worktrees based on merge status, age, or criteria
- ⚡ **Shell Completion**: Tab completion for bash/zsh/fish with quick navigation
- ⚙️ **Flexible Configuration**: Customize AI tool, presets, and defaults
- 🎨 **Type-Safe**: Built with type hints and modern Python practices

## Installation

### Using uv (recommended)

```bash
uv tool install claude-worktree
```

### Using pip

```bash
pip install claude-worktree
```

### From source

```bash
git clone https://github.com/DaveDev42/claude-worktree.git
cd claude-worktree
uv pip install -e .
```

## Quick Start

### 1. Create a new feature worktree

```bash
cw new fix-auth
```

This will:
- Create a new branch named `fix-auth`
- Create a worktree at `../myproject-fix-auth/`
- Launch Claude Code in that directory

### 2. Work on your feature

Make changes, commit them, and test your code in the isolated worktree.

### 3. Finish and merge

```bash
cw finish --push
```

This will:
- Rebase your feature onto the base branch
- Fast-forward merge into the base branch
- Clean up the worktree and feature branch
- Optionally push to remote with `--push`

## Usage

### Create a new worktree

```bash
# Create from current branch
cw new feature-name

# Specify base branch
cw new fix-bug --base develop

# Custom path
cw new hotfix --path /tmp/urgent-fix

# Launch Claude in iTerm (macOS)
cw new feature --iterm

# Launch Claude in tmux
cw new feature --tmux my-session
```

### List worktrees

```bash
cw list
```

Output:
```
Worktrees for repository: /Users/dave/myproject

BRANCH                              STATUS     PATH
refs/heads/main                     clean      .
refs/heads/fix-auth                 active     ../myproject-fix-auth
refs/heads/feature-api              modified   ../myproject-feature-api
```

**Status Types:**
- `active` (bold green) - Currently in this worktree directory
- `clean` (green) - No uncommitted changes
- `modified` (yellow) - Has uncommitted changes
- `stale` (red) - Directory deleted, needs `cw prune`

### Show status

```bash
cw status
```

### Resume AI work in a worktree

```bash
# Resume in current worktree
cw resume

# Resume in a specific worktree
cw resume fix-auth
```

### Delete a worktree

```bash
# Delete by branch name
cw delete fix-auth

# Delete by path
cw delete ../myproject-old-feature

# Keep branch, only remove worktree
cw delete feature --keep-branch

# Also delete remote branch
cw delete feature --delete-remote
```

### Prune stale worktrees

```bash
cw prune
```

Removes administrative data for worktrees with "stale" status (directories that have been manually deleted).

### Batch cleanup worktrees

```bash
# Delete merged worktrees
cw clean --merged

# Delete stale worktrees
cw clean --stale

# Delete worktrees older than 30 days
cw clean --older-than 30

# Interactive selection
cw clean -i

# Preview what would be deleted
cw clean --merged --dry-run
```

Use `--dry-run` to preview which worktrees would be deleted before actually removing them.

### Synchronize with base branch

```bash
# Sync current worktree
cw sync

# Sync specific worktree
cw sync fix-auth

# Sync all worktrees
cw sync --all

# Only fetch, don't rebase
cw sync --fetch-only
```

Fetches latest changes and rebases your feature branch onto the updated base branch. Useful for long-running features.

### Health check

```bash
cw doctor
```

Performs comprehensive health checks:
- Git version compatibility (minimum 2.31.0)
- Worktree accessibility (detects stale worktrees)
- Uncommitted changes detection
- Worktrees behind base branch
- Existing merge conflicts
- Cleanup recommendations

### Compare branches

```bash
# Full diff between branches
cw diff main feature-api

# Show diff statistics only
cw diff main feature-api --summary

# Show changed files list
cw diff main feature-api --files
```

### Visualize worktree hierarchy

```bash
cw tree
```

Displays an ASCII tree showing:
- Base repository at the root
- Feature worktrees as branches
- Status indicators (clean, modified, stale)
- Current worktree highlighting

### View statistics

```bash
cw stats
```

Shows comprehensive analytics:
- Total worktrees count and status distribution
- Age statistics (average, oldest, newest)
- Commit activity across worktrees
- Top 5 oldest worktrees
- Top 5 most active worktrees by commit count

### Template management

```bash
# Create template from current directory
cw template create my-python-setup

# Create with description
cw template create my-setup . -d "My project template"

# List all templates
cw template list

# Show template details
cw template show my-setup

# Apply template to current directory
cw template apply my-setup

# Apply to specific path
cw template apply my-setup ../feature

# Delete template
cw template delete my-setup
```

Templates help you reuse common worktree setups across projects.

### Stash management

```bash
# Save changes in current worktree
cw stash save
cw stash save "work in progress"

# List all stashes (organized by worktree)
cw stash list

# Apply stash to different worktree
cw stash apply fix-auth
cw stash apply feature-api --stash stash@{1}
```

Worktree-aware stashing makes it easy to move changes between worktrees.

### Finish with advanced options

```bash
# Interactive mode with confirmations
cw finish -i

# Preview merge without executing
cw finish --dry-run

# Get AI help with conflict resolution
cw finish --ai-merge

# Finish specific worktree from anywhere
cw finish fix-auth --push
```

The `--ai-merge` flag launches your configured AI tool if conflicts are detected during rebase.

## Command Reference

### Core Commands

| Command | Description |
|---------|-------------|
| `cw new <name>` | Create new worktree with specified branch name |
| `cw finish [branch]` | Rebase, merge, and cleanup worktree |
| `cw resume [branch]` | Resume AI work in worktree with context restoration |
| `cw list` | List all worktrees with status |
| `cw status` | Show current worktree metadata |
| `cw delete <target>` | Delete worktree by branch name or path |
| `cw prune` | Prune stale worktree administrative data |

### Maintenance & Cleanup

| Command | Description |
|---------|-------------|
| `cw clean --merged` | Delete worktrees for merged branches |
| `cw clean --stale` | Delete worktrees with stale status |
| `cw clean --older-than <days>` | Delete worktrees older than N days |
| `cw clean -i` | Interactive cleanup with selection UI |
| `cw sync [branch]` | Sync worktree(s) with base branch |
| `cw sync --all` | Sync all worktrees |
| `cw doctor` | Health check and diagnostics |

### Analysis & Visualization

| Command | Description |
|---------|-------------|
| `cw tree` | Display worktree hierarchy in tree format |
| `cw stats` | Show usage analytics and statistics |
| `cw diff <branch1> <branch2>` | Compare two branches |
| `cw diff <branch1> <branch2> --summary` | Show diff statistics only |
| `cw diff <branch1> <branch2> --files` | Show changed files list |

### Template Management

| Command | Description |
|---------|-------------|
| `cw template create <name> [path]` | Create template from directory |
| `cw template list` | List all available templates |
| `cw template show <name>` | Show template details |
| `cw template apply <name> [path]` | Apply template to directory |
| `cw template delete <name>` | Delete template |

### Stash Management

| Command | Description |
|---------|-------------|
| `cw stash save [message]` | Save changes with worktree prefix |
| `cw stash list` | List stashes organized by worktree |
| `cw stash apply <branch>` | Apply stash to different worktree |

### Configuration

| Command | Description |
|---------|-------------|
| `cw config show` | Show current configuration |
| `cw config set <key> <value>` | Set configuration value |
| `cw config use-preset <name>` | Use AI tool preset |
| `cw config list-presets` | List available presets |
| `cw config reset` | Reset to defaults |
| `cw upgrade` | Upgrade to latest version |

### Navigation

| Command | Description |
|---------|-------------|
| `cw cd <branch>` | Print worktree path (or use `cw-cd` shell function) |
| `cw _shell-function <shell>` | Output shell function for sourcing |

## Shell Completion

Enable shell completion for better productivity:

```bash
# Install completion for your shell
cw --install-completion

# Restart your shell or source your config
```

Now you can use tab completion:
```bash
cw <TAB>          # Shows available commands
cw new --<TAB>    # Shows available options
```

## Shell Function for Quick Navigation

Install the `cw-cd` shell function to quickly navigate between worktrees:

```bash
# For bash/zsh
source <(cw _shell-function bash)

# For fish
cw _shell-function fish | source

# Add to your shell config for permanent installation
echo 'source <(cw _shell-function bash)' >> ~/.bashrc  # or ~/.zshrc
```

Usage:
```bash
# Navigate to any worktree by branch name
cw-cd fix-auth
cw-cd feature-api

# Tab completion works too!
cw-cd <TAB>
```

## Configuration

### AI Tool Configuration

By default, `claude-worktree` launches Claude Code, but you can configure it to work with other AI coding assistants like Codex or Happy:

```bash
# Show current configuration
cw config show

# Set a custom AI tool
cw config set ai-tool claude
cw config set ai-tool codex
cw config set ai-tool "happy --backend claude"

# Use a predefined preset
cw config use-preset claude         # Claude Code (default)
cw config use-preset codex          # OpenAI Codex
cw config use-preset happy          # Happy with Claude Code
cw config use-preset happy-codex    # Happy with Codex mode
cw config use-preset happy-yolo     # Happy with bypass all permissions
cw config use-preset no-op          # Disable AI tool launch

# List available presets
cw config list-presets

# Reset to defaults
cw config reset
```

Configuration is stored in `~/.config/claude-worktree/config.json`.

#### Configuration Priority

1. Environment variable (`CW_AI_TOOL`)
2. Config file (`~/.config/claude-worktree/config.json`)
3. Default (`claude`)

Example using environment variable:
```bash
CW_AI_TOOL="aider" cw new feature-name
```

### Using Happy (Mobile Claude Code)

[Happy](https://github.com/slopus/happy-cli) is a mobile-enabled wrapper for Claude Code that allows you to control coding sessions from your phone.

#### Installation

```bash
npm install -g happy-coder
```

#### Quick Start

```bash
# Use Happy preset (Claude Code with mobile)
cw config use-preset happy

# Create worktree with Happy
cw new my-feature

# QR code will appear for mobile connection
```

#### Permission Modes

Happy supports different permission modes for faster iteration:

```bash
# Standard mode (default)
cw config use-preset happy

# Codex mode with bypass permissions
cw config use-preset happy-codex

# YOLO mode - bypass all permissions (fastest, use in sandboxes)
cw config use-preset happy-yolo
```

#### Using Happy with Codex

```bash
# Switch to Codex mode
cw config use-preset happy-codex
cw new my-feature
```

#### Advanced Configuration

```bash
# Custom Happy server
export HAPPY_SERVER_URL=https://my-server.com
cw config set ai-tool "happy"

# Pass additional arguments to Claude
cw config set ai-tool "happy --claude-arg --dangerously-skip-permissions"
```

### Custom AI Tools

You can use any AI coding assistant by setting a custom command:

```bash
# Set custom command
cw config set ai-tool "my-ai-tool --option value"

# Or use environment variable for one-time override
CW_AI_TOOL="aider" cw new my-feature
```

### Default Worktree Path

By default, `cw new <branch>` creates worktrees at:
```
../<repo-name>-<branch-name>/
```

For example, if your repository is at `/Users/dave/myproject` and you run `cw new fix-auth`:
- Worktree path: `/Users/dave/myproject-fix-auth/`
- Branch name: `fix-auth` (no timestamp)

### Launch Options

Control how the AI tool is launched when creating or resuming worktrees:

- `--bg`: Launch in background
- `--iterm`: Launch in new iTerm window (macOS only)
- `--iterm-tab`: Launch in new iTerm tab (macOS only)
- `--tmux <name>`: Launch in new tmux session

To skip AI tool launch entirely, use the `no-op` preset:
```bash
cw config use-preset no-op
```

### Auto-Update Settings

By default, `claude-worktree` checks for updates once per day. You can configure this behavior:

```bash
# Disable automatic update checks
cw config set update.auto_check false

# Re-enable automatic update checks
cw config set update.auto_check true

# Manual upgrade always works regardless of setting
cw upgrade
```

**When to disable auto-check:**
- Corporate environments with restricted internet
- Air-gapped systems
- CI/CD pipelines
- Personal preference for manual updates

**Note:** The `cw upgrade` command always works, even if auto-check is disabled.

## Requirements

- **Git**: Version 2.31 or higher
- **Python**: 3.11 or higher
- **AI Tool** (optional): Claude Code, Codex, Happy, or any custom AI coding assistant

## How It Works

### Metadata Storage

`claude-worktree` stores metadata in git config:

```bash
# Stores base branch for feature branches
git config branch.<feature>.worktreeBase <base>

# Stores path to main repository
git config worktree.<feature>.basePath <path>
```

This allows the `finish` command to know:
1. Which branch to rebase onto
2. Where the main repository is located
3. How to safely perform the merge

### Workflow Example

1. **Start**: You're on `main` branch in `/Users/dave/myproject`
2. **Create**: Run `cw new fix-auth`
   - Creates branch `fix-auth` from `main`
   - Creates worktree at `/Users/dave/myproject-fix-auth/`
   - Launches your configured AI tool (Claude Code by default)
3. **Work**: Make changes and commit in the worktree
4. **Finish**: Run `cw finish --push`
   - Rebases `fix-auth` onto `main`
   - Merges into `main` with fast-forward
   - Removes worktree and branch
   - Pushes to `origin/main`

## Troubleshooting

### "Not a git repository"

Make sure you're running commands from within a git repository.

### "AI tool not detected"

Install your preferred AI coding assistant:
- **Claude Code**: https://claude.ai/download
- **Codex**: Follow OpenAI's installation instructions
- **Happy**: npm install -g happy-coder

Or skip AI tool launch with the no-op preset:
```bash
cw config use-preset no-op
```

Alternatively, configure a different AI tool:
```bash
cw config set ai-tool <your-tool>
```

### "Rebase failed"

Conflicts were detected during rebase. You have two options:

**Option 1: AI-Assisted Resolution (Recommended)**
```bash
cw finish --ai-merge
```
If conflicts occur, your configured AI tool will launch to help resolve them.

**Option 2: Manual Resolution**
```bash
cd <worktree-path>
git rebase origin/<base-branch>
# Resolve conflicts
git rebase --continue
# Then run: cw finish
```

### Shell completion not working

1. Install completion: `cw --install-completion`
2. Restart your shell or source your config file
3. If still not working, check your shell's completion system is enabled

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development Setup

```bash
# Clone the repository
git clone https://github.com/DaveDev42/claude-worktree.git
cd claude-worktree

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check src/ tests/

# Run type checking
mypy src/claude_worktree
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Acknowledgments

- Inspired by git worktree workflows
- Built with [Typer](https://typer.tiangolo.com/) for the CLI
- Uses [Rich](https://rich.readthedocs.io/) for beautiful terminal output

## Links

- **Documentation**: See [CLAUDE.md](CLAUDE.md) for detailed project information
- **Issues**: https://github.com/DaveDev42/claude-worktree/issues
- **PyPI**: https://pypi.org/project/claude-worktree/
- **Changelog**: See GitHub Releases

---

Made with ❤️ for developers who love Claude Code and clean git workflows
