@thisux/pi-worktree

Git worktree slash commands for Pi.

Create, list, open, remove, and PR-checkout worktrees without leaving the session.

Layout

~/AGI/mobile/               ← main checkout
~/AGI/mobile-fix-login/     ← worktree for fix/login

Sibling folders next to the main repo: <repo>-<branch-slug>.

Install

pi install npm:@thisux/pi-worktree

Already in a session?

/reload

One-off try (no settings write):

pi -e npm:@thisux/pi-worktree

Update later:

pi update npm:@thisux/pi-worktree

Usage

Command	What it does
/worktree	List worktrees; pick one to copy path
/worktree ls	Same as above
/worktree <branch>	Create worktree for branch
/worktree add <branch>	Same as above
/worktree open <branch>	Show path (+ copy on macOS)
/worktree rm <branch>	Remove worktree (keeps branch; confirms)
/worktree pr <number>	Fetch PR via gh, create worktree
/worktree help	Show help

Create behavior

1. Local branch exists → attach worktree to it
2. Else remote origin/<branch> → track it
3. Else new branch off default (origin/main / main / master)

Path already taken by that branch → shows existing path (copied).

Remove safety

• Refuses main worktree
• Refuses locked worktrees
• Always confirms
• Dirty tree needs a second confirm before --force
• Branch is kept; only the worktree directory is removed

PR checkout

Needs GitHub CLI (gh) authenticated.

/worktree pr 42

Fetches pull/42/head and creates a worktree on the PR head branch.

Notes

• Must be inside a git repo.

• Never force-pushes, hard-resets, or clean -fdx.

• Prefer the package over a hand-copied ~/.pi/agent/extensions/git-worktree.ts — remove the loose file so it doesn't load twice:

  rm -f ~/.pi/agent/extensions/git-worktree.ts

• Enable/disable via pi config. Confirm with pi list.

Links

• npm
• pi package catalog
• Contributing
• Security
• Changelog
• Code of Conduct
• Repo

Release flow

1. Land PRs on main with conventional commits (feat:, fix:, docs:, …).
2. release-please opens a release PR (version bump + CHANGELOG.md).
3. Merge the release PR → GitHub Release/tag → CI runs bun publish.

Manual republish: Actions → Release → Run workflow (pass an existing tag).

Needs repo secret NPM_TOKEN (npm automation token allowed to publish under @thisux).

License

Copyright © 2026 THISUX Private Limited.

Released under the MIT License. You may use, modify, and distribute this project for personal and commercial purposes, provided the copyright and permission notice are retained.