https://github.com/fnebenfuehr/worktree-cli
A modern CLI tool for managing git worktrees with ease
https://github.com/fnebenfuehr/worktree-cli
ai-coding claude-code cursor git-worktree mcp
Last synced: 22 days ago
JSON representation
A modern CLI tool for managing git worktrees with ease
- Host: GitHub
- URL: https://github.com/fnebenfuehr/worktree-cli
- Owner: fnebenfuehr
- License: mit
- Created: 2025-10-15T19:28:53.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2025-12-14T15:03:07.000Z (about 2 months ago)
- Last Synced: 2025-12-16T23:18:23.008Z (about 2 months ago)
- Topics: ai-coding, claude-code, cursor, git-worktree, mcp
- Language: TypeScript
- Size: 271 KB
- Stars: 2
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://www.npmjs.com/package/@fnebenfuehr/worktree-cli)
[](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 ` | Clone repo into worktree-ready structure |
| `worktree setup` | Convert existing repo to worktrees |
| `worktree create ` | Create worktree and branch |
| `worktree checkout ` | Smart checkout: switch or create from local/remote |
| `worktree pr ` | Checkout PR branch |
| `worktree switch [branch]` | Switch to worktree (interactive if no branch) |
| `worktree list` | List all worktrees |
| `worktree remove ` | 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 ` |
| 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)