wt-cli

wt-cli is a config-driven git worktree manager for repos that need more than git worktree add.

It gives you one place to create worktrees, hydrate them, check their health, repair drift, clean them up, and jump between them from your shell.

What it does

• creates local, remote-tracking, or brand-new branch worktrees
• runs repo-specific setup steps after creation
• checks whether a worktree is actually ready to use
• repairs unhealthy worktrees by pruning and rerunning setup
• emits shell helpers so wt go feature/foo really changes directories
• supports machine-readable --json output for scripts and automation

Install

pnpm add -D @octavian-tocan/wt-cli

If you want a repo-local shortcut, add this to package.json:

{
  "scripts": {
    "wt": "wt"
  }
}

Quick start

Initialize config in a repo:

pnpm exec wt init

Create a worktree and hydrate it automatically:

pnpm exec wt create feature/search-polish

Check what exists:

pnpm exec wt list
pnpm exec wt status
pnpm exec wt doctor

Commands

• wt create <branch> - create a worktree and optionally auto-setup it
• wt go <branch> - resolve a worktree path for shell switching
• wt list - list all worktrees
• wt status - show a status overview
• wt setup [branch|path] - run setup steps for a worktree
• wt sync-env - rerun configured copy steps across worktrees
• wt clean - remove merged, stale, or orphaned worktrees
• wt doctor - inspect worktree health and readiness
• wt repair - prune and rehydrate unhealthy worktrees
• wt exec <branch> -- <command> - run a command inside a worktree
• wt init - scaffold wt.config.json
• wt shell init zsh|bash|fish - emit shell integration

Shell integration

To make wt go foo change the current shell directory instead of printing a path:

eval "$(pnpm exec wt shell init zsh)"

If wt is installed globally, wt shell init zsh works too. The generated helper falls back to pnpm exec wt or npx wt when the binary is not already on your PATH.

Config

wt-cli reads config from the first source it finds:

1. wt.config.json
2. package.json#wt

Example:

{
  "worktreeDir": "tree",
  "mainBranch": "main",
  "defaultBase": "main",
  "remote": "origin",
  "autoSetup": true,
  "staleDays": 30,
  "setup": {
    "steps": [
      { "type": "install", "command": "auto" },
      {
        "type": "copy",
        "from": ".env*",
        "to": ".",
        "exclude": [".env.example"],
        "optional": true
      },
      { "type": "run", "command": "pnpm run build:packages" },
      {
        "type": "verify",
        "path": "node_modules",
        "label": "Dependencies installed"
      }
    ]
  },
  "lifecycleScripts": {
    "postsetup": "wt:postsetup",
    "preclean": "wt:preclean"
  }
}

Setup step types

• install - install dependencies with auto-detection or an explicit command
• copy - copy files from the main worktree into the target worktree
• run - run an arbitrary command inside the worktree
• verify - assert that a path exists after setup

Canonical config only

wt-cli no longer supports the older .worktree-manager.json format or legacy config keys like buildCommand, excludeEnvFiles, and verifyPaths. Use wt.config.json or package.json#wt with the canonical setup.steps model.