pwt - Power Worktrees

A powerful Git worktree workflow for today's multi-project development.

Demos

Watch overview (mp4)

More demos in examples/ (tapes in examples/tapes, gifs in examples/gifs, how to record in examples/README.md).

✅ Work in parallel — multiple projects, or parallel changes within the same project

✅ One stable workflow — keep one editor open, swap branches underneath it

✅ No local conflicts — automatic per-worktree ports, predictable dev servers

✅ Project-aware automation — run setup, servers, and custom commands via Pwtfile

✅ Built on Git worktrees — clones when isolation is required

Install

Homebrew

brew install jonasporto/pwt/pwt

npm

npm i -g @jonasporto/pwt

npx (without installing)

npx @jonasporto/pwt --help

bun

bun add -g @jonasporto/pwt

bunx (without installing)

bunx @jonasporto/pwt --help

curl

curl -fsSL https://raw.githubusercontent.com/jonasporto/pwt/main/install.sh | bash

Dependencies: git, jq (required). fzf, lsof (optional but highly recommended).

See INSTALL.md for shell setup and troubleshooting.

Quick Start

cd ~/projects/myapp
pwt init                        # Initialize project
pwt add feat/user-auth          # Create worktree from branch
pwt cd --select                 # Interactive worktree picker
pwt list                        # List worktrees with git status

Custom commands (Pwtfile)

pwt editor                      # Open editor in current worktree
pwt build                       # Run build command
pwt server                      # Start dev server (auto port allocation)
pwt ai                          # Start AI coding assistant

Multi-Project

# See all configured projects
pwt project

# Jump to a worktree in another project
pwt backend cd security-patch

# Quick switch to another project's main
pwt backend

# Run commands in any project
pwt backend build
pwt backend server

Pwtfile

Project-specific hooks. Think Makefile, but for worktree lifecycle.

# Pwtfile
PORT_BASE=5001

setup() {
    pwtfile_copy ".env"
    pwtfile_symlink "node_modules"
    bundle install
}

server() {
    PORT="$PWT_PORT" npm start
}

Variables: $PWT_PORT, $PWT_WORKTREE, $PWT_BRANCH, $PWT_PROJECT, $MAIN_APP

Run pwt help pwtfile for full syntax.

Shell Integration

# Add to ~/.zshrc or ~/.bashrc
eval "$(pwt shell-init zsh)"

Enables pwt cd, pwt cd @, pwt cd -, and tab completion.

Everyday Commands

| Command | Description | |---------|-------------| | init | Initialize project in current repo | | add <branch> | Create worktree from branch (-e editor, -a AI) | | list | List worktrees with git status (--dirty) | | cd <worktree> | Navigate to worktree (@ main, - previous, --select) | | project | List all configured projects | | <project> cd <wt> | Jump to worktree in another project | | editor | Open editor in current worktree | | server | Start dev server (from Pwtfile) | | ai | Start AI coding assistant | | remove <worktree> | Remove worktree (--with-branch) |

Worktree vs Clone

| Mode | When to use | |------|-------------| | Worktree (default) | Most cases — faster, shares git objects | | Clone (--clone) | Submodules, or need same branch checked out twice |

Plugins

Some features ship as plugins:

pwt aitools context     # Generate AI context
pwt extras benchmark    # Compare disk usage

Create your own: pwt plugin create mycommand

Documentation

| Resource | Description | |----------|-------------| | pwt help | Quick command reference | | pwt help all | Full docs (good for LLMs) | | man pwt | Manual page | | INSTALL.md | Installation guide | | FAQ.md | Frequently asked questions | | CHANGELOG.md | Version history |

Contributing

Contributions welcome! Please open an issue first to discuss changes.

See CONTRIBUTING.md for development setup and guidelines.