Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (worktree.sh) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

worktree.sh

Zero-friction git worktree manager for parallel feature development.

中文文档 »

worktree.sh packages the repetitive setup required to spin up extra git worktrees: it creates branches, copies environment files, installs dependencies, and even starts your dev server so you can jump straight into coding.

Highlights

Launch ready-to-code worktrees with one command; automatic branch naming and directory placement keep everything tidy.
Reuse the same CLI to jump between the main repo and feature sandboxes without thinking about paths.
Configurable shell hooks keep wt available everywhere and let commands cd into the right folder automatically.
Safe cleanup helpers remove stale worktrees and their branches while preserving your project data.

Why Local Worktrees Matter for Agents

A worktree hard-isolates each agent’s context—filesystem, git history, env—so runs never cross-contaminate, the primary agent keeps its context window free, and you can hop in at any moment instead of being locked out by a non-interactive Claude Code subagent.
Spin up separate worktrees for high-variance explorations—think Claude Code “gacha” pulls on front-end UI—while Codex runs deterministic backend tasks that don’t contend for the same resources.
As models stretch into long-running sessions (minutes, hours, or more), parallel worktrees are a practical way to keep multiple agents or tasks moving without stepping on each other.
Solo developers can stay entirely local: agent-to-agent collaboration happens inside these worktrees, and pushing to a remote only matters if you need Codex Web, Codex PR Review, Claude Code PR Review, or another external service.

Quick Look

CLI overview Worktree switching

Quick Start

Install the CLI via npm (requires Node.js 14+):
```
npm install -g worktree.sh@latest
```
In the repository you want to parallelize, record it as the default project:
```
wt init
```
Spin up a new worktree:
```
wt add 3000
```
- Creates the worktree in ../project.3000
- Creates and checks out feat/3000
- Copies .env.local / .env
- Runs npm ci
- Starts npm run dev on port 3000

Jump between worktrees anytime:

wt 3000    # go to the new sandbox
wt main    # return to the primary repository

Clean up when done:
```
wt rm 3000
```

Everyday Commands

Command	What it does
`wt list`	Show tracked worktrees (wrapper over `git worktree list`).
`wt add <name>`	Create worktree, branch, copy env files, install deps, launch dev server (behavior controlled by config).
`wt <name>`	Jump straight into an existing worktree directory.
`wt rm [name ...]`	Delete current worktree or any named ones (prompts for current unless `--yes`).
`wt clean`	Batch-remove numerically named worktrees and matching `feat/*` branches.
`wt main`	Output the main repository path.
`wt config`	Inspect or tweak CLI behavior.
`wt update`	Print npm upgrade hints (for npm installs) or fall back to the legacy curl-based updater.
`wt uninstall`	Remove the binary and shell hooks.
`wt help`	Show built-in reference for all commands.

Installation Options

npm (recommended)

npm install -g worktree.sh@latest

This links wt from your global npm prefix (check npm prefix -g to confirm the directory is on your PATH). Reload your shell (source ~/.zshrc or source ~/.bashrc) and run wt init inside the repository you want as the default project.

Stable channel: npm install -g worktree.sh@latest
Preview channel: npm install -g worktree.sh@next

Upgrade with:

npm update -g worktree.sh@latest

wt update now prints the matching npm command whenever it detects an npm-managed installation.

Legacy curl installer

The original install script remains available for environments without Node.js:

Auto-detect shell:

curl -fsSL https://raw.githubusercontent.com/notdp/worktree.sh/main/install.sh | bash

Force zsh:

curl -fsSL https://raw.githubusercontent.com/notdp/worktree.sh/main/install.sh | bash -s -- --shell zsh

Force bash:

curl -fsSL https://raw.githubusercontent.com/notdp/worktree.sh/main/install.sh | bash -s -- --shell bash

When installed this way, wt update continues to download the latest script via curl.

Configuration Essentials

Settings live in ~/.worktree.sh/config.kv. Update them with wt config set:

wt config set add.serve-dev.enabled false    # Disable auto dev server
wt config set add.install-deps.enabled true  # Ensure dependencies are installed
wt config set add.branch-prefix "feature/"   # Customize branch prefixes
wt config set language zh                    # Switch CLI prompts to Simplified Chinese
wt config list                               # Inspect current values

Set the WT_CONFIG_FILE environment variable if you prefer a custom config path. The CLI reads the key/value file directly—no extra caches or daemons.

Clean Removal

When a worktree is obsolete, prune the directory and branch in one go:

wt rm              # Removes current worktree with confirmation
wt rm feat3001 feat3002    # Removes multiple named worktrees without prompting
wt clean           # Clears all numerically named worktrees

To uninstall:

curl -fsSL https://raw.githubusercontent.com/notdp/worktree.sh/main/uninstall.sh | bash

You can also run wt uninstall, which deletes the executable, removes shell hooks tagged # wt shell integration:, and backs up ~/.worktree.sh to ~/.worktree.sh.backup.<timestamp>.

Give worktree.sh a try if you iterate on multiple features in parallel; it keeps your terminals synchronized and your focus on shipping, not setup.