@maxiaochao/pi-toolkit 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-09-11 - v0.3.0
+
+- add pi-worktree CLI: one-command worktree + Pi launch with list/info/out/remove/prune and bash completion (postinstall to ~/.local/bin)
+
 ## 2026-09-09 - v0.2.6
 
 - fix cache export: segment-view tooltip and event markers now show global request numbers (aligned with the x-axis) instead of relative 1-based; e2e asserts real tooltip values

package/README.md

@@ -1,6 +1,6 @@
 # pi-toolkit
 
-Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions, bundled agent skills including Chrome/Chromium automation, and the Night Owl theme.
+Personal Pi toolkit with the `/todos`, `/btw`, and `/cache_export` extensions, bundled agent skills including Chrome/Chromium automation, the Night Owl theme, and the `pi-worktree` CLI.
 
 ## Install
 
@@ -44,6 +44,21 @@ Use `/cache_export [path]` to write an interactive per-request cache dashboard.
 
 The bundled `nightowl` theme is available to Pi through the package manifest and is selected automatically on npm installation only when no theme is already configured.
 
+## pi-worktree CLI
+
+The package also ships a standalone shell command, `pi-worktree`, that wraps Git worktree creation and Pi launch into one step. On installation (Unix-like systems) the postinstall hook copies it to `~/.local/bin/pi-worktree` and installs bash completion to `~/.local/share/bash-completion/completions/pi-worktree` (no `.bashrc` edits needed).
+
+```bash
+pi-worktree feat-ui        # create/reuse .worktrees/feat-ui, branch feat-ui, launch pi inside
+pi-worktree list           # list worktrees (main checkout marked "main checkout")
+pi-worktree info feat-ui   # base commit, ahead/behind main, unique commits
+pi-worktree out            # open a shell in the main checkout (for merging)
+pi-worktree remove feat-ui # remove the worktree (refuses unmerged branches)
+pi-worktree prune          # drop stale registrations for manually deleted dirs
+```
+
+Typical loop: `pi-worktree <name>` to start, commit inside Pi, `pi-worktree out` + `git merge <name>` to land the work, `pi-worktree remove <name>` to clean up. New branches are created from `origin/main` (falling back to `main`, then `HEAD`), and the base commit is recorded in `branch.<name>.base` config so `info` can always tell you where the branch came from. Bash completion covers subcommands and existing worktree names (`pi-worktree feat<Tab>`).
+
 The bundled `web-browser` skill provides reusable scripts for starting Chrome/Chromium with remote debugging, navigating tabs, evaluating JavaScript, emulating devices, taking screenshots, dismissing cookie dialogs, and inspecting browser logs. It auto-detects common Chrome/Chromium installations on macOS and Linux, including Windows Chrome when Pi runs under WSL; set `BROWSER_BIN` when the binary is elsewhere.
 
 The browser skill can be loaded explicitly with `/skill:web-browser`. Its scripts are available relative to the skill directory, for example:

package/bin/pi-worktree

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# pi-worktree: create/reuse a git worktree, then launch pi inside it.
+#
+# Usage:
+#   pi-worktree [name] [pi args...]     # enter worktree <name> and start pi
+#   pi-worktree -l | --list             # list worktrees (main checkout marked "main checkout")
+#   pi-worktree -i <name>               # show base commit, ahead/behind, unique commits
+#   pi-worktree -o | --out              # cd back to the main checkout
+#   pi-worktree -r <name>               # remove worktree <name> (must be clean & merged)
+#   pi-worktree -p | --prune            # drop stale worktree registrations
+set -euo pipefail
+
+# Colors: only when stdout is a TTY and NO_COLOR is unset (no-color.org)
+if [[ -t 1 && -z "${NO_COLOR:-}" ]]; then
+  C_BOLD=$'\e[1m' C_DIM=$'\e[2m' C_RED=$'\e[31m' C_GREEN=$'\e[32m' C_YELLOW=$'\e[33m' C_CYAN=$'\e[36m' C_RESET=$'\e[0m'
+else
+  C_BOLD='' C_DIM='' C_RED='' C_GREEN='' C_YELLOW='' C_CYAN='' C_RESET=''
+fi
+
+ok()      { printf '%spi-worktree:%s %s\n' "$C_GREEN" "$C_RESET" "$*"; }
+warn()    { printf '%s⚠️  %s%s\n' "$C_YELLOW" "$C_RESET" "$*"; }
+die()     { printf '%spi-worktree: %s%s\n' "$C_RED" "$C_RESET" "$*" >&2; exit 1; }
+
+require_repo() {
+  git rev-parse --is-inside-work-tree >/dev/null 2>&1 || die "not inside a git repository"
+}
+
+main_checkout() {
+  git rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||'
+}
+
+in_linked_worktree() {
+  local git_dir common_dir
+  git_dir=$(git rev-parse --git-dir 2>/dev/null) || return 1
+  common_dir=$(git rev-parse --git-common-dir 2>/dev/null) || return 1
+  [[ "$(cd "$git_dir" && pwd -P)" != "$(cd "$common_dir" && pwd -P)" ]] \
+    && [[ -z "$(git rev-parse --show-superproject-working-tree 2>/dev/null)" ]]
+}
+
+wt_dir() { echo ".worktrees/$1"; }
+
+# Best available base ref: origin/main > main > HEAD
+pick_base() {
+  if git show-ref --verify --quiet refs/remotes/origin/main; then
+    echo origin/main
+  elif git show-ref --verify --quiet refs/heads/main; then
+    echo main
+  else
+    echo HEAD
+  fi
+}
+
+ensure_gitignore() {
+  if ! git check-ignore -q .worktrees 2>/dev/null; then
+    printf '.worktrees/\n' >> .gitignore
+    ok "added .worktrees/ to .gitignore"
+  fi
+}
+
+cmd_list() {
+  require_repo
+  local main_dir; main_dir=$(main_checkout)
+  # Annotate the primary checkout and stale (prunable) entries.
+  git worktree list --porcelain | awk -v main="$main_dir" \
+    -v D="${C_DIM}" -v Y="${C_YELLOW}" -v C="${C_CYAN}" -v R="${C_RESET}" '
+    /^worktree / { path=substr($0,10); next }
+    /^HEAD /     { sha=substr($0,6); next }
+    /^branch /   { b=substr($0,8); sub("refs/heads/","",b); next }
+    /^detached/  { b="(detached)"; next }
+    /^bare/      { b="(bare)"; next }
+    /^prunable/  { stale=1; next }
+    /^$/ {
+      if (b=="") b="?"
+      mark=(path==main) ? "  " D "(main checkout)" R : ""
+      branch=(path==main) ? b : C b R
+      hint=(stale) ? "  " Y "← stale: dir gone, run: pi-worktree prune" R : ""
+      printf "%s  %s%s%s  %s%s%s\n", path, D, substr(sha,1,7), R, branch, mark, hint
+      path=""; sha=""; b=""; stale=0
+    }
+  '
+}
+
+subcmd_prune() {
+  require_repo
+  git worktree prune -v
+  ok "pruned stale worktree registrations"
+}
+
+cmd_out() {
+  cd "$(main_checkout)" && exec "${SHELL:-/bin/bash}"
+}
+
+cmd_info() {
+  require_repo
+  [[ $# -eq 1 ]] || die "usage: pi-worktree -i <name>"
+  local dir; dir="$(wt_dir "$1")"
+  [[ -d "$dir" ]] || die "worktree not found: $dir"
+  local branch; branch=$(git -C "$dir" branch --show-current)
+  echo "worktree: $dir"
+  if git -C "$dir" diff --quiet 2>/dev/null && git -C "$dir" diff --cached --quiet 2>/dev/null \
+     && [[ -z "$(git -C "$dir" ls-files --others --exclude-standard)" ]]; then
+    echo "status:   clean"
+  else
+    echo "status:   DIRTY"
+    git -C "$dir" status --short | head -10
+  fi
+  echo "branch:   $branch @ $(git -C "$dir" rev-parse --short HEAD)"
+  local base baseRef ahead behind
+  base=$(git config --get "branch.$branch.base" 2>/dev/null || true)
+  baseRef=$(git config --get "branch.$branch.baseRef" 2>/dev/null || true)
+  if [[ -n "$base" ]]; then
+    echo "based on: $baseRef @ $base"
+    ahead=$(git rev-list --count "$base..$branch" 2>/dev/null || echo "?")
+    echo "ahead:    $ahead commits since base"
+  else
+    echo "based on: (not recorded; run: git merge-base main $branch)"
+  fi
+  if git show-ref --verify --quiet refs/heads/main && [[ "$branch" != main ]]; then
+    behind=$(git rev-list --count "$branch..main" 2>/dev/null || echo "?")
+    echo "behind:   $behind commits vs main"$([[ "${behind:-0}" -gt 0 ]] && echo "  ← consider rebase")
+  fi
+  if [[ -n "$base" ]]; then
+    echo "unique commits:"
+    git log --oneline "$base..$branch" | head -5 || true
+  fi
+}
+
+cmd_remove() {
+  require_repo
+  [[ $# -eq 1 ]] || die "usage: pi-worktree -r <name>"
+  local dir; dir="$(wt_dir "$1")"
+  [[ -d "$dir" ]] || die "worktree not found: $dir"
+  # refuse to remove if the branch is not merged into main
+  local branch; branch=$(git -C "$dir" branch --show-current)
+  if [[ -n "$branch" ]] && ! git merge-base --is-ancestor "$branch" main 2>/dev/null; then
+    warn "branch '$branch' does not appear merged into 'main' (or no main branch exists)."
+    read -rp "Remove anyway? [y/N] " ans
+    [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
+  fi
+  git worktree remove "$dir" && ok "removed: $dir"
+}
+
+cd_wt() {
+  local name="$1"; shift
+  require_repo
+
+  # Already isolated? Just launch pi here (superpowers Step 0).
+  if in_linked_worktree; then
+    ok "already in an isolated worktree ($(pwd)), launching pi here"
+    exec pi "$@"
+  fi
+
+  # Dirty workspace: uncommitted changes do NOT follow into the worktree.
+  if ! git diff --quiet || ! git diff --cached --quiet || [[ -n "$(git ls-files --others --exclude-standard)" ]]; then
+    warn "Uncommitted changes stay in THIS directory; they will NOT appear in the worktree:"
+    git status --short | head -20
+    read -rp "Continue? [y/N] " ans
+    [[ "$ans" =~ ^[Yy]$ ]] || die "aborted"
+  fi
+
+  local dir; dir="$(wt_dir "$name")"
+  ensure_gitignore
+
+  if [[ -d "$dir" ]]; then
+    # Reuse: must be a registered worktree for this repo
+    git -C "$dir" rev-parse --git-dir >/dev/null 2>&1 || die "$dir exists but is not a git worktree"
+    ok "reusing existing worktree $dir"
+  else
+    mkdir -p .worktrees
+    # Reuse branch if it exists, else create it
+    if git show-ref --verify --quiet "refs/heads/$name"; then
+      git worktree add "$dir" "$name"
+      ok "checked out existing branch '$name'"
+      # record a best-effort base for -i display
+      local mb; mb=$(git merge-base main "$name" 2>/dev/null || true)
+      [[ -n "$mb" ]] && git config "branch.$name.base" "$(git rev-parse --short "$mb")" \
+        && git config "branch.$name.baseRef" main
+    else
+      local base; base=$(pick_base)
+      git worktree add "$dir" -b "$name" "$base"
+      git config "branch.$name.base" "$(git rev-parse --short "$base")"
+      git config "branch.$name.baseRef" "$base"
+      ok "created branch '$name' from $base @ $(git rev-parse --short "$base")"
+    fi
+  fi
+
+  cd "$dir"
+  exec pi "$@"
+}
+
+case "${1:-}" in
+  -l|--list|list|ls) shift; cmd_list "$@" ;;
+  -i|--info|info) shift; cmd_info "$@" ;;
+  -o|--out|out) shift; cmd_out "$@" ;;
+  -r|--remove|rm|remove) shift; cmd_remove "$@" ;;
+  -p|--prune|prune) shift; subcmd_prune ;;
+  -h|--help|help) sed -n '2,10p' "$0" | sed 's/^# \{0,1\}//' ;;
+  "")  die "usage: pi-worktree <name> [pi args...]  (or list / info / out / remove / prune)" ;;
+  *)   name="$1"; shift; cd_wt "$name" "$@" ;;
+esac

package/bin/pi-worktree-completion.bash

@@ -0,0 +1,36 @@
+# bash completion for pi-worktree
+_pi_worktree() {
+  local cur first
+  cur="${COMP_WORDS[COMP_CWORD]}"
+  first="${COMP_WORDS[1]}"
+
+  local SUBS="list ls info out remove rm prune -l --list -i --info -o --out -r --remove -p --prune -h --help"
+
+  # existing worktree names (only linked worktrees, i.e. under .worktrees/)
+  local wts=""
+  if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+    local main_dir
+    main_dir=$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null | sed 's|/.git$||')
+    wts=$(git worktree list --porcelain 2>/dev/null \
+      | sed -n 's|^worktree ||p' \
+      | while read -r p; do [[ "$p" != "$main_dir" ]] && basename "$p"; done || true)
+  fi
+
+  if (( COMP_CWORD == 1 )); then
+    # first word: subcommands, flags, and existing worktree names (to enter)
+    COMPREPLY=($(compgen -W "$SUBS $wts" -- "$cur"))
+    return
+  fi
+
+  case "$first" in
+    -i|--info|info|-r|--remove|remove|rm)
+      # second word of info/remove: worktree names only
+      COMPREPLY=($(compgen -W "$wts" -- "$cur"))
+      ;;
+    *)
+      # after a name: default (file) completion for pi args
+      COMPREPLY=()
+      ;;
+  esac
+}
+complete -F _pi_worktree pi-worktree

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "keywords": [
@@ -10,6 +10,7 @@
   "files": [
     "extensions",
     "themes",
+    "bin",
     "README.md",
     "CHANGELOG.md",
     "global/AGENTS.md",
@@ -33,6 +34,9 @@
       "./themes"
     ]
   },
+  "bin": {
+    "pi-worktree": "bin/pi-worktree"
+  },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",

package/scripts/install-agents.mjs

@@ -1,10 +1,12 @@
 // postinstall hook: sync the bundled global AGENTS.md and seed the default theme
 // without overriding a theme the user has already selected.
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
-import { homedir } from "node:os";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, copyFileSync, chmodSync } from "node:fs";
+import { homedir, platform } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
+const packageRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
 const agentDir = join(homedir(), ".pi", "agent");
 const bundled = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "global", "AGENTS.md"), "utf8");
 const agentsTarget = join(agentDir, "AGENTS.md");
@@ -41,3 +43,22 @@ if (!existsSync(settingsTarget)) {
     console.warn("[pi-toolkit] could not set default theme:", error instanceof Error ? error.message : String(error));
   }
 }
+
+// Install the pi-worktree CLI + bash completion on Unix-like systems.
+// Copy (not symlink) so the running command does not depend on the repo/node_modules layout.
+if (platform() !== "win32") {
+  try {
+    const binTarget = join(homedir(), ".local", "bin", "pi-worktree");
+    mkdirSync(dirname(binTarget), { recursive: true });
+    copyFileSync(join(packageRoot, "bin", "pi-worktree"), binTarget);
+    chmodSync(binTarget, 0o755);
+    console.log("[pi-toolkit] pi-worktree installed ->", binTarget);
+
+    const compTarget = join(homedir(), ".local", "share", "bash-completion", "completions", "pi-worktree");
+    mkdirSync(dirname(compTarget), { recursive: true });
+    copyFileSync(join(packageRoot, "bin", "pi-worktree-completion.bash"), compTarget);
+    console.log("[pi-toolkit] pi-worktree bash completion installed ->", compTarget);
+  } catch (error) {
+    console.warn("[pi-toolkit] could not install pi-worktree CLI:", error instanceof Error ? error.message : String(error));
+  }
+}