---
name: ck-worktree
description: Create isolated git worktrees for parallel feature development. Use when working on multiple features simultaneously, isolating experiments, or setting up a parallel branch without disrupting the current working directory.
---

# Worktree — Isolated Git Worktree

Creates isolated git worktrees for parallel development without switching branches.

## When to Use

- Working on multiple features simultaneously
- Isolating an experiment without stashing current work
- Setting up a parallel branch for a hotfix while mid-feature

## Don't Use When

- Repository uses a shallow clone (worktrees unsupported)
- Simple branch switch is sufficient

## Workflow

### Step 1: Get Repo Info

```bash
node $HOME/.claude/scripts/worktree.cjs info --json
```

Parse: `repoType`, `baseBranch`, `projects`, `worktreeRoot`, `worktreeRootSource`.

### Step 2: Detect Branch Prefix from Description

| Keywords | Prefix |
|----------|--------|
| fix, bug, error, issue | `fix` |
| refactor, restructure, rewrite | `refactor` |
| docs, documentation, readme | `docs` |
| test, spec, coverage | `test` |
| chore, cleanup, deps | `chore` |
| perf, performance, optimize | `perf` |
| (default) | `feat` |

### Step 3: Convert Description to Slug

`"add authentication system"` → `add-auth` (max 50 chars, kebab-case)

### Step 4: Handle Monorepo

If `repoType === "monorepo"` and project not specified, ask user which project to target.

### Step 5: Execute

**Standalone:**
```bash
node $HOME/.claude/scripts/worktree.cjs create "<SLUG>" --prefix <TYPE>
```

**Monorepo:**
```bash
node $HOME/.claude/scripts/worktree.cjs create "<PROJECT>" "<SLUG>" --prefix <TYPE>
```

### Step 6: Install Dependencies

After creating worktree, run in background based on lock file:
- `bun.lock` → `bun install`
- `pnpm-lock.yaml` → `pnpm install`
- `package-lock.json` → `npm install`
- `poetry.lock` → `poetry install`
- `Cargo.toml` → `cargo build`

## Commands

| Command | Description |
|---------|-------------|
| `create [project] <feature>` | Create worktree |
| `remove <name-or-path>` | Remove worktree |
| `info` | Repo info with worktree location |
| `list` | List all worktrees |

## Notes

- Auto-detects superproject, monorepo, and standalone repos
- Default worktree location: superproject > monorepo sibling > repo sibling
- `.env*.example` files auto-copied with `.example` suffix removed
- Use `--dry-run` to preview without creating