npm package: @fnebenfuehr/worktree-cli
Description: A modern CLI tool for managing git worktrees with ease
Author: Florian Nebenfuehr
Latest version: 1.5.0

[![npm version](https://img.shields.io/npm/v/@fnebenfuehr/worktree-cli.svg)](https://www.npmjs.com/package/@fnebenfuehr/worktree-cli)
[![license](https://img.shields.io/npm/l/@fnebenfuehr/worktree-cli.svg)](https://github.com/fnebenfuehr/worktree-cli/blob/main/LICENSE)

# Worktree CLI

Git worktree management for AI coding assistants. Enables parallel development across multiple branches without context switching.

## Why?

AI coding assistants work best with isolated contexts. Git worktrees give each task its own directory—no stashing, no branch switching, no conflicts. Your AI can work on a feature while you review a PR in another worktree.

## Quick Start

```bash
# Install
npm install -g @fnebenfuehr/worktree-cli

# Convert existing repo to worktree structure
cd your-project && worktree setup

# Create a feature worktree
worktree create feat/new-feature
```

See [docs/QUICKSTART.md](./docs/QUICKSTART.md) for detailed setup guide.

## MCP Integration

Add to your Claude Code or AI assistant config:

```json
{
  "mcpServers": {
    "worktree": {
      "command": "npx",
      "args": ["-y", "@fnebenfuehr/worktree-cli", "mcp"]
    }
  }
}
```

Your AI assistant can now:
- Check worktree status before modifications
- Create isolated worktrees for features/fixes
- Switch between work contexts
- Checkout PRs for review
- Clean up merged branches

### MCP Tools

| Tool | Description |
|------|-------------|
| `worktree_status` | Check if repo uses worktrees, current branch, default branch |
| `worktree_list` | List all worktrees with branches and paths |
| `worktree_create` | Create new worktree with branch |
| `worktree_checkout` | Intelligent checkout: switch/create from local/remote |
| `worktree_pr` | Checkout GitHub PR by number or URL |
| `worktree_switch` | Switch to existing worktree |
| `worktree_remove` | Remove worktree (with merge safety checks) |
| `worktree_setup` | Convert repo to worktree structure |

## CLI Commands

| Command | Description |
|---------|-------------|
| `worktree clone <url>` | Clone repo into worktree-ready structure |
| `worktree setup` | Convert existing repo to worktrees |
| `worktree create <branch>` | Create worktree and branch |
| `worktree checkout <branch>` | Smart checkout: switch or create from local/remote |
| `worktree pr <number\|url>` | Checkout PR branch |
| `worktree switch [branch]` | Switch to worktree (interactive if no branch) |
| `worktree list` | List all worktrees |
| `worktree remove <branch>` | Remove worktree |
| `worktree update` | Update CLI to latest version |

## Configuration

Create `.worktree.json` in your repo root (auto-generated by `setup`/`clone`):

```json
{
  "defaultBranch": "main",
  "post_create": ["npm install"],
  "pre_remove": ["docker compose down"],
  "copy_files": [".env", ".env.local"]
}
```

| Option | Description |
|--------|-------------|
| `defaultBranch` | Base branch for new worktrees |
| `post_create` | Commands to run after creating worktree |
| `pre_remove` | Commands to run before removing worktree |
| `post_remove` | Commands to run after removing worktree |
| `copy_files` | Files to copy from main worktree |

Hooks receive environment variables: `WORKTREE_PATH`, `WORKTREE_BRANCH`, `WORKTREE_MAIN_PATH`.

## Comparison

| Task | Manual Git | Worktree CLI |
|------|------------|--------------|
| Create feature branch | `git worktree add -b feat/x ../feat-x origin/main` | `worktree create feat/x` |
| Switch context | `cd ../other-worktree` | `worktree switch other` |
| Setup new repo | Multiple commands + directory management | `worktree clone <url>` |
| Post-create setup | Manual: install deps, copy .env | Automatic via hooks |
| PR review | Stash → checkout → review → checkout → pop | `worktree pr 123` |
| AI integration | Manual git commands | Native MCP server |

## Directory Structure

After setup, your repo looks like:

```
project/
├── main/           # default branch worktree
├── feat-auth/      # feature worktree
└── fix-bug/        # bugfix worktree
```

Each directory is a complete working copy with shared git history.

## Documentation

- [Quick Start Guide](./docs/QUICKSTART.md)
- [AI Coding Workflows](./docs/AI_WORKFLOWS.md)
- [Hooks Configuration](./docs/HOOKS.md)

## License

MIT

## Links

- [Issues](https://github.com/fnebenfuehr/worktree-cli/issues)
- [Discussions](https://github.com/fnebenfuehr/worktree-cli/discussions)