Archived

This project has been archived by its maintainers, and is no longer receiving any updates.

Claude Worktree

Work on multiple git branches simultaneously with isolated AI coding sessions

What is this?

claude-worktree (command: cw) helps you work on multiple features at the same time by creating separate directories for each branch. No more switching branches, stashing changes, or losing context.

Each feature gets:

✅ Its own directory (git worktree)
✅ Its own AI coding session (Claude Code, Codex, or custom)
✅ Zero interference with other work

Perfect for developers who want to:

Work on multiple features in parallel
Keep AI conversation context for each feature
Never lose work when switching tasks
Cleanly merge features without conflicts

Why Use This?

No More Branch Switching Chaos

Before claude-worktree:

# Working on feature-api
git add .
git stash  # Save current work
git checkout main
git checkout -b fix-urgent-bug
# Fix bug, commit
git checkout feature-api
git stash pop  # Hope nothing conflicts
# Where was I?

With claude-worktree:

cw new fix-urgent-bug
# Fix bug in separate directory
cw merge fix-urgent-bug --push
# Return to feature-api - it's untouched

Each feature stays isolated, AI context is preserved, and switching is instant.

Lightning-Fast Workflow with Shell Completion

Tab completion makes everything faster:

cw <TAB>              # All commands appear
cw new --<TAB>        # All options for 'new' command
cw resume <TAB>       # Your branch names
cw-cd <TAB>           # Jump to any worktree instantly

No more typing long commands or remembering branch names - just type and press Tab.

Quick Start

Install

# Using uv (recommended)
uv tool install claude-worktree

# Or using pip
pip install claude-worktree

Basic Usage

# 1. Create a new feature worktree
cw new fix-login-bug

# This creates:
# - A new branch: fix-login-bug
# - A new directory: ../myproject-fix-login-bug/
# - Launches Claude Code in that directory

# 2. Work on your feature
# (AI helps you, you commit changes, etc.)

# 3. When done, create a PR
cw pr

# Or merge directly (for solo projects)
cw merge --push

That's it! You've just created an isolated workspace with AI assistance, worked on your feature, and merged it back.

Key Features

Essential Commands

Command	What it does
`cw new <name>`	Create new feature worktree + launch AI
`cw new <name> --term i-t`	Create worktree, launch AI in iTerm tab
`cw list`	Show all your worktrees
`cw resume [branch]`	Resume AI session in a worktree
`cw pr`	Create GitHub pull request
`cw merge`	Merge to base branch and cleanup
`cw delete <name>`	Remove a worktree

Enable tab completion for faster workflow:

# Install completion (bash/zsh/fish/PowerShell)
cw --install-completion

# Restart your shell, then enjoy:
cw <TAB>          # Shows available commands
cw new --<TAB>    # Shows available options
cw resume <TAB>   # Shows branch names

Windows PowerShell users:

# Install completion for PowerShell
cw --install-completion powershell

# Restart PowerShell, then use tab completion:
cw <TAB>          # Shows available commands
cw resume <TAB>   # Shows branch names

Quick navigation between worktrees:

# Interactive setup (recommended):
cw shell-setup

# Or install manually:
# bash/zsh: Add to ~/.bashrc or ~/.zshrc
source <(cw _shell-function bash)

# fish: Add to ~/.config/fish/config.fish
cw _shell-function fish | source

# PowerShell: Add to $PROFILE
cw _shell-function powershell | Invoke-Expression

# Then use:
cw-cd feature-api    # Jump to any worktree instantly
cw-cd <TAB>          # Tab completion works!

Example Workflow

Scenario: Working on multiple features

# Start 3 features at once
cw new feature-api
cw new fix-bug-123
cw new refactor-db

# Check what you have
cw list
#  BRANCH           STATUS    PATH
#  main             clean     .
#  feature-api      active    ../myproject-feature-api
#  fix-bug-123      modified  ../myproject-fix-bug-123
#  refactor-db      clean     ../myproject-refactor-db

# Resume work on a specific feature
cw resume fix-bug-123

# Complete features as they're done
cw pr feature-api        # Create PR
cw merge fix-bug-123 --push  # Direct merge

Scenario: Team collaboration

# Create feature and share
cw new team-feature
git push -u origin team-feature

# Stay in sync with team
cw sync team-feature

# Compare before merging
cw diff main team-feature --summary

# Create PR for review
cw pr --title "Add awesome feature"

Configuration

AI Tool Selection

By default, cw launches Claude Code. You can easily change this:

# Use a preset
cw config use-preset claude              # Claude Code (default)
cw config use-preset claude-remote       # Remote control (phone/tablet)
cw config use-preset codex               # OpenAI Codex
cw config use-preset no-op               # Skip AI launch

# Or set custom tool
cw config set ai-tool "your-ai-tool"

# List available presets
cw config list-presets

Auto-Copy Files

Automatically copy project-specific files (like .env) to new worktrees:

# Add files to copy list
cw config copy-files add .env
cw config copy-files add .env.local
cw config copy-files add config/local.json

# List configured files
cw config copy-files list

# Remove a file from the list
cw config copy-files remove .env

Note: Dependencies like node_modules and .venv are automatically symlinked (not copied) to save disk space.

For detailed configuration options (remote control, auto-updates, export/import, etc.), see Configuration Guide.

More Features

Maintenance & Cleanup: cw clean, cw sync, cw doctor Analysis: cw tree, cw stats, cw diff Backup & Restore: cw backup create/restore Stash Management: cw stash save/apply

See Advanced Features Guide for details.

Command Reference

For the complete command reference with all options, see Commands Documentation or run:

cw --help
cw <command> --help

Requirements

Git: 2.31+ (for worktree support)
Python: 3.11+
AI Tool (optional): Claude Code, Codex, or custom

Installation Methods

Using uv (recommended)

uv tool install claude-worktree

Using pip

pip install claude-worktree

From source

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

Troubleshooting

"Not a git repository"

Run commands from within a git repository.

"AI tool not detected"

Install your AI tool or skip AI launch:

cw config use-preset no-op

"Rebase failed"

Resolve conflicts manually:

cd <worktree-path>
git rebase <base-branch>
# Fix conflicts
git rebase --continue
cw pr  # or cw merge --push

Shell completion not working

cw --install-completion
# Restart shell

For more troubleshooting help, see TROUBLESHOOTING.md.

Documentation

User Guides

Commands Reference - Complete command reference with all options
Configuration Guide - AI tools, presets, shell completion, export/import
Advanced Features - Backup/restore, sync, cleanup, CI/CD
Troubleshooting - Common issues and solutions

Contributing

Contributions welcome! For development setup:

git clone https://github.com/DaveDev42/claude-worktree.git
cd claude-worktree
uv pip install -e ".[dev]"

# Run tests
uv run --extra dev pytest

# Run linting
ruff check src/ tests/
mypy src/claude_worktree

For maintainers: Use the automated release script to create new releases:

# Create a patch release (0.10.20 → 0.10.21)
uv run python scripts/release.py

# Create a minor release (0.10.20 → 0.11.0)
uv run python scripts/release.py --minor

# Create a major release (0.11.0 → 1.0.0)
uv run python scripts/release.py --major

CHANGELOG management: The changelog is automatically generated from GitHub Releases. When a release PR is merged:

GitHub automatically creates a Release with notes (PR-based)
Workflow updates CHANGELOG.md from Releases
Changes are committed to main

To manually update the changelog:

python scripts/changelog_sync.py

See CLAUDE.md for detailed development and release workflows.

License

MIT License - see LICENSE file for details.

Acknowledgments

Built with Typer and Rich for a great CLI experience.

Made for developers who love AI-assisted coding and clean git workflows 🚀

Metadata

Release files for claude-worktree 0.10.54

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for claude-worktree 0.10.54
File	Size	Uploaded
claude_worktree-0.10.54.tar.gz	222.6 kB	Mar 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for claude-worktree 0.10.54
File	Interpreter	ABI	Platform	Reset
claude_worktree-0.10.54-py3-none-any.whl 109.7 kB Mar 18, 2026	Python 3	none	any	Details

Total release size: 332.3 kB

Release files / claude_worktree-0.10.54.tar.gz

Download URL	claude_worktree-0.10.54.tar.gz
Size	222.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`697b12cd739c2cf9e7655a563a1388cc03b950b0d28738c156c20280e1a8e53f`
BLAKE2b-256 checksum How to use checksums	`e442ded005d60cb5d810b0731b554fb63b5ad7d1b09a4caf6dba8c40dea6754b`
Upload date	Mar 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/DaveDev42/claude-worktree
Publishing commit: github.com/DaveDev42/claude-worktree/tree/a9892ce94c6b6e322b2a21b15cb3910746189ce6

Workflow

Publishing configuration: github.com/DaveDev42/claude-worktree/blob/a9892ce94c6b6e322b2a21b15cb3910746189ce6/.github/workflows/publish.yml
Publishing logs: github.com/DaveDev42/claude-worktree/actions/runs/23234422481/attempts/1

Artifact

Subject: claude_worktree-0.10.54.tar.gz
SHA-256 checksum: 697b12cd739c2cf9e7655a563a1388cc03b950b0d28738c156c20280e1a8e53f Verifying attestations

Release files / claude_worktree-0.10.54-py3-none-any.whl

Download URL	claude_worktree-0.10.54-py3-none-any.whl
Size	109.7 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`18dadd039755a43ecb5026e2d3bdbbdc2f0ea2c152e76d478ce3f1e938443597`
BLAKE2b-256 checksum How to use checksums	`83067ce2d51f6fc7da099036652f463cfc6eeec699678386646e786d050e76a6`
Upload date	Mar 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/DaveDev42/claude-worktree
Publishing commit: github.com/DaveDev42/claude-worktree/tree/a9892ce94c6b6e322b2a21b15cb3910746189ce6

Workflow

Publishing configuration: github.com/DaveDev42/claude-worktree/blob/a9892ce94c6b6e322b2a21b15cb3910746189ce6/.github/workflows/publish.yml
Publishing logs: github.com/DaveDev42/claude-worktree/actions/runs/23234422481/attempts/1

Artifact

Subject: claude_worktree-0.10.54-py3-none-any.whl
SHA-256 checksum: 18dadd039755a43ecb5026e2d3bdbbdc2f0ea2c152e76d478ce3f1e938443597 Verifying attestations