Wt

wt — Git Worktree Isolation

You are managing git worktrees with isolated Postgres databases, managed Redis Docker containers, and ports using the wt CLI.

Routing

Based on the first argument, perform one of the following:

init — First-time setup for a repository

The user wants to set up wt in their project for the first time. Follow these steps exactly:

Step 1: Discover the project

Search the repository to find:

• All .env files (not .env.example): find . -name '.env' -not -path '*/node_modules/*' -not -path '*/.git/*'
• The DATABASE_URL value to extract the base database name (path segment after the port, before ?)
• Any REDIS_URL values and their base port/auth format
• All services and their default ports — check package.json scripts, docker-compose.yml, framework config files
• The package manager in use (pnpm, npm, yarn) — check for lockfiles

Step 2: Map env vars to patch types

For each .env file, examine every variable and classify:

Step 3: Generate wt.config.json

Build the config file at the repository root:

{
  "baseDatabaseName": "<extracted from DATABASE_URL>",
  "baseWorktreePath": ".worktrees",
  "portStride": 100,
  "maxSlots": 50,
  "services": [
    { "name": "<service>", "defaultPort": <port> },
    { "name": "redis", "defaultPort": <port from REDIS_URL or 6379> }
  ],
  "envFiles": [
    {
      "source": "<relative path to .env file>",
      "patches": [
        { "var": "<VAR_NAME>", "type": "<database|redis|port|url>", "service": "<name>" }
      ]
    }
  ],
  "postSetup": ["<install command>"],
  "autoInstall": true
}

Validation rules:

• Every redis, port, and url patch must have a service that exists in services
• portStride * maxSlots + max default port must be < 65535
• baseDatabaseName must match the actual DB name in DATABASE_URL
• If using a redis patch, Docker must be available locally

Step 4: Install wt

# Detect package manager and install
pnpm add -D @tokenbooks/wt

Step 5: Update .gitignore

Add .worktree-registry.json if not already present.

Step 6: Add convenience scripts to root package.json

{
  "scripts": {
    "wt": "wt",
    "wt:new": "wt new",
    "wt:list": "wt list",
    "wt:doctor": "wt doctor"
  }
}

Step 7: Create .husky/post-checkout hook (if husky is installed)

#!/bin/bash
prev_head="$1"
new_head="$2"
is_branch="$3"
[ "$is_branch" = "0" ] && exit 0
git_common=$(git rev-parse --git-common-dir 2>/dev/null)
git_dir=$(git rev-parse --git-dir 2>/dev/null)
[ "$git_common" = "$git_dir" ] && exit 0
main_worktree=$(cd "$git_common/.." && pwd -P)
wt_bin="$main_worktree/node_modules/.bin/wt"
if [ ! -f "$wt_bin" ]; then
  wt_bin=$(command -v wt 2>/dev/null || true)
fi
if [ -z "$wt_bin" ]; then
  echo "Warning: wt CLI not found."
  exit 0
fi
echo "Setting up worktree environment..."
"$wt_bin" setup "$(pwd -P)" --json 2>/dev/null && echo "Worktree ready!" || {
  echo "Warning: Auto-setup failed. Run 'wt setup' manually."
  exit 0
}

Make it executable: chmod +x .husky/post-checkout

Step 8: Smoke test

wt list                              # Should show "No worktree allocations found."
wt doctor                            # Should show "All checks passed."
wt new test/wt-smoke --no-install    # Create a test worktree
wt list                              # Should show the allocation
wt remove .worktrees/test-wt-smoke   # Clean up
wt prune --dry-run                   # Should show no Git-prunable worktrees

Present the results to the user.

open $1 — Open (or create) a worktree

Run:

wt open $1

Accepts a slot number (1) or branch name (feat/auth). If a branch isn't found in the registry, it creates a new worktree automatically.

Tip: use cd $(wt open $1) to jump into the worktree directory.

new $1 — Create a new worktree

Run:

wt new $1

If it fails, check wt doctor for diagnostics. Common issues:

• All slots occupied → suggest wt list to find stale ones, then wt remove or wt prune
• Database connection failed → check that Postgres is running and DATABASE_URL in root .env is correct

list — List all worktree allocations

Run:

wt list

remove [targets...]|--all — Remove one or more worktrees

Run:

wt remove $@

Accepts paths or slots, not branch names, including batch slot formats:

• wt remove 1 2
• wt remove 1,2
• wt remove "1, 2"
• wt remove --all

If the user wants to keep the database, use --keep-db.

prune — Prune Git-prunable worktrees

Run:

wt prune $@

Use this when worktree directories were deleted manually and Git already marks them as prunable.

Flags:

• --dry-run to preview what would be pruned
• --keep-db to keep databases for matching managed allocations

doctor — Diagnose issues

Run:

wt doctor

If issues are found, ask the user if they want to auto-fix:

wt doctor --fix

setup — Set up an existing worktree

Run:

wt setup $1

Use this when a worktree was created with plain git worktree add instead of wt new.

No arguments or unrecognized command

Show a brief help:

Available commands:
  /wt init              — Set up wt in a new repository (discovers env files, generates config)
  /wt new <branch>      — Create a worktree with isolated DB, managed Redis, and ports
  /wt open <slot|branch> — Open a worktree by slot or branch (creates if not found)
  /wt list              — List all worktree allocations
  /wt remove <targets...>|--all — Remove one or more worktrees and clean up resources
  /wt prune [--dry-run] — Prune Git-prunable worktrees and clean up matching managed resources
  /wt doctor            — Diagnose and fix environment issues
  /wt setup [path]      — Set up an existing worktree

Converted and distributed by TomeVault — claim your Tome and manage your conversions.