pi-worktree

Git worktree management for Pi Coding Agent. Create isolated dev environments with one command — each with its own branch, database, dependencies, and ports.

Inspired by claude --worktree from Claude Code.

Why?

When working on multiple features in parallel (or running multiple AI coding agents), you need full isolation — not just a git branch, but separate node_modules, databases, env files, and dev server ports. Git worktrees provide the branch isolation; pi-worktree automates everything else via project-level hooks.

One command gets you:

• A fresh git worktree on its own branch
• A dedicated database (via createdb or any command you configure)
• A generated .env.local with worktree-specific config
• Installed dependencies (npm install / bun install)
• Applied migrations or schema pushes
• Pi running in the worktree directory, ready to code

Install

pi install pi-worktree

If Pi is already running, use /reload to pick up the new extension.

Usage

# Create a worktree and start Pi in it
pi --worktree my-feature

# Auto-generated name (e.g. "calm-fox")
pi --worktree

# From within a Pi session
/worktree my-feature
/worktree destroy my-feature
/worktree list

When cmux or tmux is detected, Pi relaunches itself in the worktree directory within the same terminal. Without a multiplexer, it prints the path for manual cd && pi.

Project configuration

Create .pi/worktree.json in your repo root (commit it so all contributors share the same setup). Run /skill:worktree-setup for interactive setup, or create it manually:

{
  "dir": ".worktrees",
  "branchPrefix": "worktree/",
  "linkEnvFiles": true,
  "postCreate": [
    "npm install",
    "npx prisma db push"
  ],
  "preRemove": [
    "dropdb --if-exists myapp_$(basename $PWD) 2>/dev/null || true"
  ]
}

| Key | Default | Description | |-----|---------|-------------| | dir | .worktrees | Directory for worktrees (relative to repo root) | | branchPrefix | worktree/ | Branch name prefix | | linkEnvFiles | true | Symlink gitignored .env* files (except .env.local) from main repo | | postCreate | [] | Shell commands run after creation (cwd = worktree) | | preRemove | [] | Shell commands run before removal (cwd = worktree) |

Don't forget to add the worktree directory to .gitignore:

.worktrees/

How it works

Create (pi --worktree my-feature or /worktree my-feature):

1. git worktree add -b worktree/my-feature .worktrees/my-feature HEAD
2. Symlinks gitignored .env* files (except .env.local) from the main repo
3. Runs each postCreate command in order
4. Relaunches Pi in the worktree directory

Destroy (/worktree destroy my-feature):

1. Runs each preRemove command
2. git worktree remove --force .worktrees/my-feature
3. git branch -D worktree/my-feature

Relaunch strategy: Pi's tools (bash, read, edit, etc.) bind to the working directory at startup via closure — there is no way to change it mid-session. When a worktree is created from the main repo, Pi shuts down and injects cd <worktree> && pi into the terminal via cmux send or tmux send-keys, so Pi restarts with the correct cwd.

Examples

Node.js + PostgreSQL + Prisma

Each worktree gets its own database and .env.local:

{
  "postCreate": [
    "printf 'DATABASE_URL=postgres://localhost:5432/myapp_%s\\n' $(basename $PWD) > .env.local",
    "createdb myapp_$(basename $PWD) 2>/dev/null || true",
    "npm install",
    "npx prisma db push"
  ],
  "preRemove": [
    "dropdb --if-exists myapp_$(basename $PWD) 2>/dev/null || true"
  ]
}

Bun monorepo with per-worktree staging

For monorepos where each worktree needs a unique stage name (for isolated dev server ports), database, and environment:

{
  "postCreate": [
    "WT=$(basename $PWD); DB=myapp_$(echo $WT | tr '-' '_'); printf 'STAGE=%s\\nDATABASE_URL=postgres://localhost:5432/%s\\n' \"$WT\" \"$DB\" > .env.local",
    "DB=$(grep DATABASE_URL .env.local | sed 's|.*/||'); createdb \"$DB\" 2>/dev/null || true",
    "bun install",
    "bun run prisma:generate",
    "bun run prisma:push"
  ],
  "preRemove": [
    "DB=$(grep DATABASE_URL .env.local 2>/dev/null | sed 's|.*/||'); [ -n \"$DB\" ] && dropdb --if-exists \"$DB\" 2>/dev/null || true"
  ]
}

This pattern works well for projects that derive dev server ports from the stage name, giving each worktree fully isolated services.

Update

pi update pi-worktree

License

MIT