pi-worktrees/README.md

pi-worktree

A pi extension for managing git worktrees through intuitive tool commands and an interactive picker.

Tools

git_worktree_create

Create a linked worktree for a branch in the current repo.

{
  path: string,           // Path for the new worktree
  branch?: string,        // Branch name (new or existing). Defaults to 'main'.
  create_branch?: boolean // Create a new branch? Defaults to true if branch doesn't exist.
}

Example: git_worktree_create({ path: "./feature-x", branch: "feature-x" })

git_worktree_list

List all linked worktrees in the current repo.

// No parameters required

Returns structured data with branch, path, and isCurrent for each worktree.

Example output:

main — /home/user/repo (current)
feature-x — /home/user/repo/feature-x

git_worktree_switch

Switch pi's working directory to a linked worktree.

{
  target: string   // Path or branch name of the target worktree
}

Example: git_worktree_switch({ target: "./feature-x" })

After switching, you'll be offered the option to create a new session for that worktree context.

git_worktree_remove

Remove a linked worktree.

{
  path: string   // Path of the worktree to remove
}

Example: git_worktree_remove({ path: "./feature-x" })

Command

/worktree

Interactive picker to switch between linked worktrees.

Lists all worktrees with a branch-first display and lets you select one to switch to. Automatically updates pi's branch display after switching.

Behavior

• Fail fast: Refuses dangerous operations (existing paths, current branch, uncommitted changes) with clear messages and suggested fixes.
• Stateless tools: Each call works independently based on current git state.
• Session integration: Branch display updates automatically; you're offered a new session after switching worktrees.
• Back-switching: When returning to the main repo, pi restores the previous session.

Requirements

• Git 2.x with worktree support (all modern versions)
• No external npm dependencies — uses only pi's extension API and TypeBox schemas.