pi-worktrees

pi-worktrees adds a /wt command to Pi for creating, switching, returning from, and deleting managed Git worktrees without leaving your coding session. It is built for clean branch isolation, quick experiments, and safer parallel work across tasks.

Highlights

• One-command worktrees: create a new Git worktree and switch Pi into it immediately.
• Native Pi experience: interactive TUI overlay with search, keyboard navigation, badges, and confirmations.
• Safe managed storage: keeps Pi-created worktrees under a predictable managed directory.
• Return flow: jump back from a managed worktree to the original project with /wt return.
• Optional change transfer: move uncommitted changes with --move when creating or returning.
• Deletion guardrails: confirms destructive deletes and warns when a worktree has uncommitted changes.

Requirements

• Pi with extension support
• Node.js compatible with Pi extensions
• Git with git worktree support
• pnpm for local development

Installation

Install from npm

Install the extension in Pi with:

pi install npm:pi-worktrees

After installation, restart Pi or use /reload if your session supports hot reload. The /wt command will be available in your Pi session.

Install from Git

After this repository is public, you can also install it directly from GitHub:

pi install git:github.com/0xkuze/pi-worktrees

For a one-off run without adding it to your settings:

pi -e git:github.com/0xkuze/pi-worktrees

Use a local checkout

git clone git@github.com:0xkuze/pi-worktrees.git
cd pi-worktrees
pnpm install
pi -e ./src/index.ts

For hot reload during development, place or symlink the package into a Pi extension location such as .pi/extensions/pi-worktrees/ or ~/.pi/agent/extensions/pi-worktrees/, then use /reload inside Pi.

Usage

Open the worktree overlay:

/wt

Create a managed worktree and switch to it:

/wt create feature-name

Create a worktree and move uncommitted changes into it:

/wt create feature-name --move

Return from a managed worktree to the original project:

/wt return

Return and move uncommitted changes back to the original project:

/wt return --move

Delete a managed worktree:

/wt delete /absolute/path/to/worktree

Commands

Command	Description
/wt	Opens the interactive worktree overlay.
/wt create [name]	Creates a managed worktree on branch wt/<name> and switches Pi to it.
/wt create [name] --move	Stashes current changes, creates the worktree, and pops the stash there.
/wt return	Returns from a managed worktree to the original project.
/wt return --move	Stashes worktree changes and pops them in the original project.
/wt delete <path>	Removes a managed worktree after confirmation.

Aliases are also supported for convenience: new for create, back for return, and remove/rm for delete.

TUI shortcuts

Shortcut	Action
↑ / ↓ or j / k	Move through the worktree list.
/	Search worktrees.
Enter	Switch to the selected worktree.
⌘N or n	Create a new worktree.
d	Delete the selected managed worktree.
Esc or q	Close the overlay.

When the overlay is opened from a managed worktree, the original project appears with a [project] badge so you can return quickly.

Managed storage

By default, managed worktrees are stored under:

~/.local/share/pi-worktrees

Set PI_WORKTREE_HOME to choose a custom storage root:

export PI_WORKTREE_HOME="$HOME/.worktrees/pi"

Worktree names are normalized to kebab-case. If you omit a name, pi-worktrees generates one automatically.

How change transfer works

When you pass --move, pi-worktrees uses Git stash commands across worktrees in the same repository:

1. git stash push -u in the source worktree
2. worktree creation or return navigation
3. git stash pop in the destination worktree

If you choose not to move changes, they remain in the current worktree.

Development

Install dependencies:

pnpm install

Run the full validation suite:

pnpm check

Run only TypeScript validation:

pnpm build

Run tests:

pnpm test

Project structure

src/
  errors/    Error formatting and typed error helpers
  git/       Git command wrappers and worktree parsing
  session/   Pi session switching integration
  storage/   Managed paths, metadata, and name normalization
  ui/        TUI overlay implementation
  worktree/  Create, return, delete, and overlay data flows

Publishing checklist

Before publishing or sharing publicly:

• Ensure the repository visibility is set to public on GitHub.
• Run pnpm check and confirm the build and tests pass.
• Review the package metadata in package.json.
• Choose and add a license if you want others to reuse, modify, or redistribute the code.

Author

Created and maintained by Cristian Fonseca.