# Worktree

Create, reuse, and clean up git worktrees under $VIBE_HOME/worktrees.

- Repository: https://github.com/mistralai/mistral-vibe (5270 stars)
- Category: Git and review
- License: Apache-2.0
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mistralai/mistral-vibe --skill worktree -g -a claude-code -y`
Codex: `npx skills add mistralai/mistral-vibe --skill worktree -g -a codex -y`
Cursor: `npx skills add mistralai/mistral-vibe --skill worktree -g -a cursor -y`
Gemini CLI: `npx skills add mistralai/mistral-vibe --skill worktree -g -a gemini-cli -y`

## Description

Create, reuse, and clean up git worktrees under $VIBE_HOME/worktrees. Use when the user wants to work in an isolated git worktree, create a worktree for a task, or list/remove existing worktrees.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Worktree Management

Git worktrees live under `$VIBE_HOME/worktrees/` (default `~/.vibe/worktrees/`),
each in a per-repository bucket named `<repo_root.name>-<sha256(common_git_dir)[:12]>`
so worktrees from different repos never collide.

```
$VIBE_HOME/worktrees/
  .claims/<bucket>/<name>/          # claim records and holder markers
    record.json                     # metadata: branch, base_commit, branch_created, claimed_at
    recovery.json                   # snapshot metadata for a retained chat
    holders/                        # one empty file per live session
  <bucket>/<name>/                  # the actual git worktree checkout
```

## Creating a worktree

1. Compute the bucket from the repo root and common git dir.
2. Validate the name (single portable path segment; no `<>:"/\|?*`, no
   trailing space or dot, no Windows reserved names like `CON`/`PRN`/`NUL`/
   `COM1`-`COM9`/`LPT1`-`LPT9`, not `.` or `..`).
3. Reserve the directory with `mkdir` (atomic claim, fails if taken).
4. For a new branch, start from the remote's default branch (fetch first,
   best-effort). For an existing branch, check it out into the worktree.
5. `git worktree add -b <name> <path> <start_point>` (or without `-b` for reuse).
6. Record the worktree's own HEAD as `base_commit`, this is the baseline for
   cleanup, not the invoking checkout's HEAD.
7. Write `record.json` under `.claims/<bucket>/<name>/`.

When no name is given, derive one by slugifying the prompt: NFKD-normalize,
lowercase, replace non-`[a-z0-9]+` with `-`, take the first 6 words, trim to
40 chars, drop trailing stop words. Branch gets a `vibe/` prefix. Append
`-2`, `-3`, etc. on collision (up to 100). Fall back to a random slug if empty.

Reuse an existing worktree only after validating: no symlinks in the path,
`.git` is a file (not a directory), same common git dir, matching branch.

## Holding

The rest: https://github.com/mistralai/mistral-vibe/blob/HEAD/vibe/plugins/builtins/vibe/skills/worktree/SKILL.md