CLI tool for managing Git worktrees efficiently with GitHub integration
npm install wt-managerThe dashboard Git forgot to include.
Git worktrees let you work on multiple branches simultaneously—but managing them? That's where the fun ends.
- "Which folder was that again?" - You have 5 worktree directories and zero memory of which one has feature/auth
- The GitHub tab dance - Constantly switching to check if that PR got merged yet, or if it's still sitting in review purgatory
- Stale worktree graveyard - Merged PRs pile up as forgotten worktrees, each one silently judging your organizational skills
- Three tools, zero coordination - Git knows your worktrees. GitHub knows your PRs. Your filesystem knows your folders. They don't talk to each other.
wt gives you the dashboard Git forgot to include.
The wt list command shows you everything:
- All your worktrees with their PR status (open/draft/merged/closed)
- Which branches are ahead/behind
- CI check status (passing/failing)
- Uncommitted changes warnings
And when you're done? wt clean finds all merged/closed PRs and removes their worktrees and branches in one go. It even asks nicely before deleting anything.
Requirements: Bun 1.0+, Git, and GitHub CLI (gh auth login)
``bashInstall globally
bun install -g wt-manager
Commands
$3
Create a new worktree for a new branch. Worktrees are created in
../ directory.`bash
Create worktree from default branch
wt new feature/new-featureCreate worktree from specific base branch
wt new feature/new-feature develop
`Arguments:
-
- Name of the new branch to create
- [base-branch] - Base branch to create from (default: auto-detected from origin/HEAD)Behavior:
- Automatically creates the worktree directory structure
- Converts slashes in branch names to dashes for directory names (e.g.,
feature/foo → feature-foo)
- Shows spinner during creation
- Fails if branch already exists locally
- Copies/symlinks files based on .wtrc.js config (see Configuration)
- Runs post-create commands from config
- Copies worktree path to clipboard for easy navigation$3
List all worktrees with their status, PR information, and branch details.
`bash
List all worktrees with status
wt listJSON output format
wt list --json
`Options:
-
--json - Output in JSON format (disables spinner)Output includes:
- Worktree directory name
- PR status (open/draft/merged/closed/no-pr)
- Branch ahead/behind counts relative to default branch
- Uncommitted changes indicator
- CI check status (passing/failing)
- Current worktree indicator
- PR URL (if available)
- Summary statistics
Example output:
`
Worktrees for my-repo:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━feature-auth open (↑3 ↓0)
Branch: feature/auth
PR: https://github.com/owner/repo/pull/123
bugfix-login merged (↑0 ↓2)
Branch: bugfix/login
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Summary: 2 worktrees (1 open, 1 merged)
💡 Run 'wt clean' to remove 1 merged/closed worktree(s)
`$3
Remove worktrees for branches with merged or closed PRs, abandoned folders, and orphan worktrees. Uses interactive checkbox selection.
`bash
Clean up merged/closed worktrees (interactive)
wt cleanDry run to see what would be removed
wt clean --dry-runSkip interactive selection (select all)
wt clean --force
`Options:
-
-d, --dry-run - Show what would be removed without actually removing
- -f, --force - Skip interactive selection (removes all cleanable items)What it detects:
- Merged/Closed worktrees - Worktrees with merged or closed PRs
- Abandoned folders - Directories in worktrees folder without
.git (leftover from manual deletions)
- Orphan worktrees - Directories with .git file pointing to non-existent gitdirSafety features:
- Shows spinner while checking PR status
- Automatically skips worktrees with uncommitted changes (warns user)
- Skips the current worktree
- Interactive checkbox selection to choose what to remove
- Automatically deletes local branch when removing worktree
- Only processes worktrees in
directoryExample flow:
`
Scanning worktrees...
Checking PR status...
Scanning for abandoned folders...⚠ Skipped (uncommitted changes):
bugfix-draft (bugfix/draft)
? Select worktrees to remove:
❯ ◯ feature-old (MERGED)
◯ bugfix-done (CLOSED)
◯ leftover-dir (abandoned)
◯ broken-wt (orphan)
Removing feature-old...
✓ Removed: feature-old (branch deleted)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ Cleaned up 1 worktree(s)!
Run 'wt list' to see remaining worktrees.
`$3
Remove a specific worktree by name. Interactive with safety prompts for uncommitted changes and unpushed commits.
`bash
Remove by branch name
wt remove feature/my-featureRemove by directory name
wt remove feature-my-featureKeep the local branch (only remove worktree)
wt remove feature/my-feature --keep-branchForce removal (skip all prompts)
wt remove feature/my-feature --force
`Arguments:
-
- Worktree name (matches branch name or directory name)Options:
-
--keep-branch - Keep the local branch after removing the worktree
- -f, --force - Force removal even with uncommitted changes or unpushed commitsSafety features:
- Shows uncommitted changes before removal
- Option to view diff before discarding changes
- Warns about unpushed commits before branch deletion
- Warns about branches with no remote tracking
- Interactive prompts to abort, keep branch, or proceed
Example flow:
`
Worktree: feature-my-feature
Path: /path/to/repo-worktrees/feature-my-feature
Branch: feature/my-feature⚠ Uncommitted changes detected:
Modified:
src/file.ts
? What would you like to do?
❯ Show diff
Discard changes and remove
Abort
✓ Removed worktree: feature-my-feature
✓ Deleted branch: feature/my-feature
Run 'wt list' to see remaining worktrees
`$3
Select a worktree interactively and copy its path to clipboard. Useful for quick navigation.
`bash
Interactive selection
wt pathFuzzy match and copy directly
wt path authQuiet mode for scripting (prints raw path, no clipboard)
wt path -q feature
cd $(wt path -q feature)
`Arguments:
-
[name] - Optional fuzzy match on branch or directory nameOptions:
-
-q, --quiet - Output path only (for scripting). Requires name argument.Behavior:
- Without argument: Shows interactive list of worktrees to select from
- With argument: Fuzzy matches and copies path directly to clipboard
- With
-q: Prints raw path to stdout (no spinner, no clipboard, no colors)
- Shows PR status and ahead/behind counts in the selection listExample:
`
? Select worktree:
❯ ● feature-auth (↑2 ↓0) [open]
○ feature-api (↑5 ↓1) [draft]
○ bugfix-login [merged]✓ Copied to clipboard: /path/to/repo-worktrees/feature-auth
`$3
Show quick status of the current worktree.
`bash
wt status
`Output includes:
- Branch name with ahead/behind counts
- PR status and check runs (if available)
- Modified and untracked file counts
Example output:
`
feature/auth (↑2 ↓5)
PR #42 open - ✓ checks passing
https://github.com/owner/repo/pull/42
3 modified, 1 untracked
`$3
Initialize a
.wtrc.js configuration file in the current repository.`bash
wt init
`Behavior:
- Creates
.wtrc.js in the main worktree root with default configuration
- If config already exists, shows a message and exits without overwriting$3
Check environment and configuration for potential issues.
`bash
wt doctor
`Checks performed:
| Check | Pass | Warn/Fail |
|-------|------|-----------|
| Git installed | Shows version | Error |
| Inside git repo | Shows repo name | Error |
| GitHub CLI installed | Shows version | Warning with install link |
| GitHub CLI authenticated | Shows username | Warning to run
gh auth login |
| Worktrees directory | Shows count | Info if none yet |
| Config file | Shows if found | Info if using defaults |Example output:
`
Checks:
✓ Git: 2.43.0
✓ Repository: my-repo
✓ GitHub CLI: 2.40.0
✓ GitHub auth: username
✓ Worktrees: 3 worktrees in ../my-repo-worktrees
○ Config: using defaults (no .wtrc.js)All checks passed!
`Configuration
Create a
.wtrc.js file in your repository root to configure worktree behavior (or use wt init):`javascript
export default {
worktreePath: '$REPO-worktrees/$DIR',
copy: [
'.idea/runConfigurations/**',
'.idea/codeStyles/**',
'!.idea/workspace.xml'
],
symlink: [
'.env'
],
postCreate: 'npm install && code $PATH',
}
`$3
| Option | Type | Default | Description |
|--------|------|---------|-------------|
|
worktreePath | string | $REPO-worktrees/$DIR | Path template for new worktrees (relative to parent of main repo) |
| copy | string[] | [] | Glob patterns for files to copy from main worktree |
| symlink | string[] | [] | Glob patterns for files to symlink from main worktree |
| postCreate | string | '' | Command to run after creating worktree |$3
Use these variables in
worktreePath and postCreate:| Variable | Description | Example |
|----------|-------------|---------|
|
$REPO | Repository name | my-repo |
| $BRANCH | Original branch name | feature/auth |
| $DIR | Directory-safe branch name (slashes → dashes) | feature-auth |
| $PATH | Full worktree path | /path/to/my-repo-worktrees/feature-auth |$3
Copy and symlink patterns use gitignore-style globs:
-
.env - single file
- .idea/** - entire directory
- !.idea/workspace.xml - exclude specific file
- *.config.js - wildcard matching$3
The
postCreate string runs via sh -c in the new worktree directory. Use shell syntax for chaining:`javascript
export default {
postCreate: 'npm install && code $PATH',
}
`$3
`bash
wt config
`Shows the active configuration with resolved paths.
GitHub Integration
This tool integrates with GitHub to provide rich PR information:
- PR Status - Displays open/draft/merged/closed state
- PR URLs - Direct links to pull requests
- CI Checks - Shows if checks are passing or failing
- Smart Cleanup - Identifies branches safe to remove based on PR state
- Draft Detection - Shows when PRs are in draft state
$3
Uses existing GitHub CLI (
gh) authentication. Make sure you're logged in:`bash
gh auth login
`The tool will show helpful error messages if:
-
gh CLI is not installed
- You're not authenticated
- The repository doesn't have a GitHub remote$3
The tool works without GitHub integration, but with limited functionality:
-
wt list will show "no-pr" status for all worktrees
- wt clean requires GitHub CLI and won't work without itWorkflow Example
Here's a typical workflow using these tools:
`bash
Create a new worktree for a feature
wt new feature/add-authNavigate to the worktree (path copied to clipboard)
cd ../my-repo-worktrees/feature-add-authOr use wt path to get the path
wt path auth
✓ Copied to clipboard: /path/to/repo-worktrees/feature-add-auth
Work on your feature...
git add .
git commit -m "Add authentication"
git push -u origin feature/add-authCreate PR via gh CLI
gh pr create --title "Add authentication" --body "Implements user auth"Check status of current worktree
wt status
feature/add-auth (↑1 ↓0)
PR #42 open - ✓ checks passing
Check status of all worktrees
wt list
Shows: feature-add-auth (open)
After PR is merged, clean up
wt clean
Removes merged worktree and deletes branch
`Installation
$3
`bash
bun install -g wt-manager
`$3
Download pre-built binaries from GitHub Releases:
| Platform | Binary |
|----------|--------|
| macOS ARM64 (M1/M2) |
wt-darwin-arm64 |
| macOS x64 (Intel) | wt-darwin-x64 |
| Linux x64 | wt-linux-x64 |
| Linux ARM64 | wt-linux-arm64 |
| Windows x64 | wt-windows-x64.exe |`bash
Example: macOS ARM64
curl -L https://github.com/daviddurika/git-worktree-manager/releases/latest/download/wt-darwin-arm64 -o ~/.local/bin/wt
chmod +x ~/.local/bin/wt
`Make sure
~/.local/bin is in your PATH.Development
$3
`bash
bun run build
`$3
`bash
bun run dev
`$3
`bash
bun run lint
bun run format
``MIT