@maxiaochao/pi-toolkit 0.2.5 → 0.3.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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
+
 ## 2026-09-09 - v0.2.5
 
 - fix cache export: segment views lost the hover tooltip (it rendered inside the hidden all-history section); move to one page-level tooltip; e2e now asserts real rendering

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/extensions/cache-export/render.ts

@@ -205,8 +205,12 @@ function lineChart(title, series, opts = {}) {
   ];
 
   const tsAttr = timestamps ? ` data-timestamps="${esc(timestamps.join("|"), true)}"` : "";
+  // Global per-request numbers (same length as the series) so a small page
+  // script can rewrite tau's relative "Request N" tooltip line to the global
+  // number inside segment views (tau hardcodes index + 1).
+  const reqAttr = requestNumbers ? ` data-requestnumbers="${esc(requestNumbers.join("|"), true)}"` : "";
   const parts = [
-    `<svg class="usage-chart" viewBox="0 0 ${width} ${height}" role="img" aria-label="${esc(title, true)}" data-left="${left}" data-right="${right}" data-count="${count}"${tsAttr}>`,
+    `<svg class="usage-chart" viewBox="0 0 ${width} ${height}" role="img" aria-label="${esc(title, true)}" data-left="${left}" data-right="${right}" data-count="${count}"${tsAttr}${reqAttr}>`,
     `<text class="chart-title" x="${left}" y="24">${esc(title)}</text>`,
   ];
   for (let tick = 0; tick < 6; tick++) {
@@ -233,7 +237,10 @@ function lineChart(title, series, opts = {}) {
     .forEach((event, eventIndex) => {
       const [x] = point(Math.max(0, Math.min(count - 1, event.requestNumber - 1)), 0);
       const markerY = top + 7 + (eventIndex % 3) * 9;
-      const description = `${event.label} before request ${event.requestNumber} at ${event.timestamp}`;
+      // data-request stays RELATIVE (tau's tooltip matches index + 1); the human
+      // description shows the GLOBAL request number (chartEvents keeps it).
+      const shown = event.globalRequestNumber ?? event.requestNumber;
+      const description = `${event.label} before request ${shown} at ${event.timestamp}`;
       parts.push(
         `<g class="usage-event usage-event-${esc(event.kind, true)}" data-request="${event.requestNumber}" ` +
           `data-event-info="${esc(description, true)}" role="img" aria-label="${esc(description, true)}">` +
@@ -542,10 +549,14 @@ function eventsForRequests(events, requests) {
   return events.filter((event) => event.requestNumber >= from && event.requestNumber <= to);
 }
 
-function chartEvents(events, requests) {
+export function chartEvents(events, requests) {
   if (!requests.length) return [];
   const first = requests[0].number;
-  return events.map((event) => ({ ...event, requestNumber: event.requestNumber - first + 1 }));
+  return events.map((event) => ({
+    ...event,
+    requestNumber: event.requestNumber - first + 1, // relative, for tau's data-request matching
+    globalRequestNumber: event.requestNumber,        // absolute, for readable labels
+  }));
 }
 
 function renderDashboardView(requests, events, toolCalls, compactions, scopeLabel) {
@@ -756,6 +767,23 @@ for (const select of document.querySelectorAll("[data-context-segment-select]"))
   select.addEventListener("change", show);
   show();
 }
+// tau's tooltip hardcodes "Request " + (index + 1), which is relative inside a
+// segment view while the x-axis shows global request numbers. Rewrite the
+// tooltip's leading request number to the chart's global number on hover.
+// Registered after tau's own pointermove listener, so it runs after tau writes.
+document.querySelectorAll(".usage-chart").forEach((chart) => {
+  const nums = (chart.dataset.requestnumbers || "").split("|").map(Number);
+  chart.addEventListener("pointermove", () => {
+    const tooltip = document.querySelector(".usage-tooltip");
+    if (!tooltip) return;
+    const m = tooltip.textContent.match(/^Request (\\d+)/);
+    if (!m) return;
+    const global = nums[Number(m[1]) - 1];
+    if (global && global !== Number(m[1])) {
+      tooltip.textContent = tooltip.textContent.replace(/^Request \\d+/, "Request " + global);
+    }
+  });
+});
 </script>
 </main></body></html>`;
 }

package/extensions/cache-export/tests/e2e-browser.mjs

@@ -269,7 +269,8 @@ async function run() {
     check("e2e no IndexSizeError / uncaught errors in All view",
       !allCharts.errs.some((e) => /IndexSizeError|Uncaught/i.test(e)), JSON.stringify(allCharts.errs));
 
-    // 3. latest segment view (no internal breaks): full-width tooltips
+    // 3. latest segment view (no internal breaks): full-width tooltips aligned
+    //    to GLOBAL request numbers (fixture segment-4 = requests 40..45)
     await evalJs(`window.__probe.setView("segment-4")`);
     const seg4 = await evalJs(`
       (() => {
@@ -281,9 +282,28 @@ async function run() {
     check("e2e segment-4 tooltip works at start and end",
       seg4.near.visible && seg4.far.visible && seg4.farReq !== seg4.nearReq,
       JSON.stringify(seg4));
+    check("e2e segment-4 tooltip aligns to GLOBAL request numbers (40..45, not 1..6)",
+      seg4.nearReq === 40 && seg4.farReq === 45,
+      JSON.stringify(seg4));
     check("e2e segment view has no uncaught errors",
       !seg4.errs.some((e) => /IndexSizeError|Uncaught/i.test(e)), JSON.stringify(seg4.errs));
 
+    // 4. event markers in a segment view keep relative data-request for tau
+    //    matching but describe the GLOBAL request number
+    await evalJs(`window.__probe.setView("segment-2")`);
+    const ev = await evalJs(`
+      (() => {
+        const chart = [...document.querySelectorAll("svg.usage-chart")]
+          .find((s) => s.getAttribute("aria-label") === "Prompt input by request" &&
+            s.closest(".usage-context-view") && !s.closest(".usage-context-view").hidden);
+        const g = chart.querySelector(".usage-event");
+        return g ? { dataRequest: g.getAttribute("data-request"), info: g.getAttribute("data-event-info") } : null;
+      })()
+    `);
+    check("e2e segment event marker: data-request relative, description global",
+      ev && ev.dataRequest === "1" && ev.info.includes("before request 25"),
+      JSON.stringify(ev));
+
     cdp.close();
     if (usesWindowsChrome && windowsPid) {
       try { execFileSync("taskkill.exe", ["/PID", String(windowsPid), "/T", "/F"]); } catch { /* best effort */ }

package/extensions/cache-export/tests/run-tests.mjs

@@ -4,7 +4,7 @@ import { mkdtempSync, readFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import registerCacheExport from "../index.ts";
-import { parseEntries, analyzeStreaks, analyzeMisses, buildContextSegments, lineChartForTest, renderDashboard } from "../render.ts";
+import { parseEntries, analyzeStreaks, analyzeMisses, buildContextSegments, lineChartForTest, renderDashboard, chartEvents } from "../render.ts";
 
 let pass = 0, fail = 0;
 function check(name, cond, detail = "") {
@@ -346,6 +346,23 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
     dashboard.slice(0, 500));
 }
 
+// P3. segment-view request numbers align to global (tooltip override + event labels)
+{
+  const chart = lineChartForTest("seg", [["cached", [1, 2, 3]]], { requestNumbers: [40, 41, 42] });
+  check("P3 chart carries global data-requestnumbers", chart.includes('data-requestnumbers="40|41|42"'), chart.slice(0, 220));
+  const ev = chartEvents([{ kind: "model", requestNumber: 310, label: "Model changed to b", timestamp: "12:00:00" }], [{ number: 310 }, { number: 311 }, { number: 312 }]);
+  check("P3 chartEvents keeps relative requestNumber (tau matching) and global label number",
+    ev[0].requestNumber === 1 && ev[0].globalRequestNumber === 310,
+    JSON.stringify(ev[0]));
+  const labeled = lineChartForTest("seg", [["cached", [1, 2, 3]]], {
+    requestNumbers: [310, 311, 312],
+    events: [{ kind: "model", requestNumber: 1, label: "Model changed to b", timestamp: "12:00:00", globalRequestNumber: 310 }],
+  });
+  check("P3 event description shows global request while data-request stays relative",
+    labeled.includes("before request 310 at 12:00:00") && labeled.includes('data-request="1"'),
+    labeled.slice(0, 700));
+}
+
 // Q. subagent results remain visible as main-session tool input -----------
 {
   const entries = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.2.5",
+  "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));
+  }
+}