pi-worktree

Pi package that keeps agent work out of the main checkout by routing file and shell tools into an isolated Git worktree.

What it does

pi-worktree bundles:

• a Pi extension that creates and activates task worktrees
• safety routing for file tools and bash
• lifecycle tools for status, diff, sync, commit, stop, and cleanup
• a worktree-router skill that teaches agents when to use the workflow
• a colored footer status item showing the active worktree path and branch

When active, Pi stays attached to the original repository, but tool execution happens inside the active worktree.

⧉ .worktree/refactor/selector-code-style | ⎇ refactor/selector-code-style

Install

From this checkout:

pi install /Users/mrscraper56/Projects/Code/Personal/monang/my-pi/packages/pi-worktree

Or from any directory with the same absolute path:

cd /
pi install /Users/mrscraper56/Projects/Code/Personal/monang/my-pi/packages/pi-worktree

Restart Pi or run /reload after reinstalling.

Quick test

Open Pi inside any Git repository:

cd /path/to/repo
pi

Ask:

use worktree for this feature: add a small README note

The extension detects the activation phrase and blocks file/bash tools until worktree_start succeeds.

Verify:

Call worktree_status

Expected shape:

pi-worktree active: /path/to/repo/.worktree/feat/example on feat/example

Check bash routing:

Run bash: pwd && echo "$PI_WORKTREE_ROOT" && git branch --show-current

Expected:

/path/to/repo/.worktree/feat/example
/path/to/repo/.worktree/feat/example
feat/example

Tools

worktree_start

Creates and activates a worktree.

Inputs:

{
  prompt?: string;
  branch?: string;
  baseRef?: string;
  trustMise?: boolean;
}

Branch inference:

• feature → feat/<slug>
• bug/fix → fix/<slug>
• docs → docs/<slug>
• refactor → refactor/<slug>
• test → test/<slug>

Worktree path preserves branch segments:

branch: refactor/selector-code-style
path:   .worktree/refactor/selector-code-style

worktree_status

Shows active state, full worktree path, branch, and git status --short --branch.

worktree_resolve_file

Shows where a path will route without reading or writing it.

worktree_resolve_file({ path: "src/main.ts" })

Expected while active:

src/main.ts -> /repo/.worktree/<branch>/src/main.ts

worktree_diff

Shows git diff --stat and git diff for the active worktree. Output is truncated safely.

worktree_sync

Fetches and rebases the active worktree onto latest upstream without touching the main checkout.

Default target detection:

1. origin/HEAD
2. origin/main
3. local main
4. HEAD

worktree_commit

Commits inside the active worktree only. Requires explicit UI confirmation.

Inputs:

{
  message: string;
  all?: boolean;
}

worktree_stop

Deactivates routing. Optionally removes the worktree.

Inputs:

{
  remove?: boolean;
  force?: boolean;
}

Dirty worktrees are not removed unless force: true is passed.

worktree_rescue_leftovers

Lists leftover .worktree directories and can remove clean leftovers.

Routing behavior

When active:

| Input path | Result | |---|---| | src/a.ts | routes to active worktree | | ./src/a.ts | routes to active worktree | | /repo/src/a.ts | remaps to /repo/.worktree/<branch>/src/a.ts | | /repo/.worktree/<active>/src/a.ts | allowed | | /repo/.worktree/<other>/src/a.ts | blocked | | ~/.pi/agent/skills/tdd/SKILL.md | allowed as a Pi-managed path | | /etc/passwd | blocked | | ../outside | blocked |

Safety checks use real filesystem resolution and block symlink escapes. Pi-managed paths (~/.pi and the running Pi package) pass through so skills, package docs, and Pi internals remain readable while routing is active.

Bash behavior

The package overrides Pi's bash tool with a spawn hook.

When active:

• cwd is the active worktree root
• PI_WORKTREE_ROOT is set
• PI_WORKTREE_BRANCH is set
• PI_WORKTREE_REPO_ROOT is set

Pi's process cwd and status bar may still show the original repo. Use worktree_status or pwd to verify effective execution location.

Footer

The extension installs a compact custom footer with the fields used during agent work:

⧉ .worktree/refactor/selector-code-style @ ⎇ refactor/selector-code-style | my-pi | GPT-5.5 think:high | ctx 29.5%/272k AC | cache 3.0M

Fields:

• model name
• thinking effort
• current directory basename
• worktree label/path (main-worktree when routing is inactive)
• branch
• context usage with auto-compaction marker (AC)
• cache-read total

Colors:

• model/thinking: magenta
• directory/worktree icon/path: cyan
• branch icon/name: green
• context/cache: blue
• separator: dim gray
• pending: yellow
• conflict: red warning

If a Pi version does not support custom footers, pi-worktree falls back to its old extension status item.

@ picker limitation

The package routes execution, not Pi's resource index.

Worktree-only new files may not appear in Pi's @ picker because the picker indexes the original repo context. You can still type normal relative paths manually; file tools route them to the active worktree.

Example:

docs/plans/2026-06-01-selector-code-style.md

Future work: hook Pi resource/autocomplete events if the API supports path source override.

Development

cd packages/pi-worktree
npm install
npm test
npm run typecheck

Package resources

{
  "pi": {
    "extensions": ["./extensions/index.ts"],
    "skills": ["./skills"]
  }
}