pi-worktree-tui-status

A TUI-only worktree and experiment status indicator for Pi.

It shows which git worktree or disposable experiment the agent is touching when the agent edits or runs commands against long paths like:

runs/agents/worktrees/<slug>/...
runs/experiments/<product-or-app>/<slug>/...

It does not create, switch, remove, prune, checkout, merge, promote, or otherwise manage worktrees or experiments.

🌳 issue-1234-fix-camera | 🌿 1234-fix-camera | dirty +3
🧪 bistro-beacon/camera-spike | experiment

Why this exists

Some workflows keep Pi's current working directory on the main repository, while the agent works in an isolated git worktree by using explicit long paths:

git worktree add runs/agents/worktrees/my-task my-branch
git -C runs/agents/worktrees/my-task status --short

Statusline extensions that inspect only ctx.cwd will still show the original checkout. This extension watches Pi tool calls and user shell commands, detects worktree or experiment paths, and updates a small TUI status item.

Install

pi install npm:pi-worktree-tui-status

Try without installing:

pi -e npm:pi-worktree-tui-status

Local development:

git clone https://github.com/arpagon/pi-worktree-tui-status.git
cd pi-worktree-tui-status
pi -e ./index.ts

If Pi is already running, use /reload after installing.

What it detects

Tool paths

It watches path-like arguments from Pi tool calls, including:

• read
• write
• edit
• grep
• find
• ls
• any tool with path, cwd, file, directory, or target string fields

Examples:

{
  "path": "runs/agents/worktrees/my-task/src/index.ts"
}

{
  "path": "runs/experiments/bistro-beacon/camera-spike/report.md"
}

Bash commands

It also watches bash commands and user ! shell commands for:

git -C runs/agents/worktrees/my-task status --short
npm --prefix runs/agents/worktrees/my-task/app test
python runs/experiments/bistro-beacon/camera-spike/run.py

Display

The extension writes one Pi status segment:

🌳 <slug> | 🌿 <branch> | <clean | dirty +N | dirty ?>
🧪 <product-or-app>/<slug> | experiment

Examples:

🌳 issue-workflow-fix | 🌿 1943-improve-issue-workflow | clean
🌳 roi-camera-plan | 🌿 2110-roi-camera-plan | dirty +4
🧪 bistro-beacon/camera-spike | experiment

Non-goals

This package is intentionally narrow:

• No /worktree command
• No git worktree creation
• No checkout/switch behavior
• No path redirection
• No shell sandboxing
• No cleanup or deletion
• No PR or merge automation
• No experiment creation, promotion, cleanup, or archival

Use a worktree management extension if you want those behaviors. Use this package only when you want a visual TUI indicator.

Project workflow compatibility

This is designed for workflows like:

gh issue develop <issue> --base main --name <branch>
git fetch origin <branch>
git worktree add -b <branch> runs/agents/worktrees/<slug> origin/<branch>
git -C runs/agents/worktrees/<slug> status --short

The agent can keep Pi's cwd in the original repo and still get a visible indication of which worktree is being touched. Disposable exploration under runs/experiments/<product-or-app>/<slug> is shown as experiment mode.

Development

npm test
npm run typecheck
npm run pack:dry
npm run validate

Package contents

The npm package includes only:

index.ts
README.md
CHANGELOG.md
LICENSE
AGENTS.md

Security

Pi extensions run with your user permissions. This extension does not execute arbitrary user-provided shell commands. Experiment detection only parses paths. For worktrees, it runs read-only git commands against detected worktree roots:

git -C <worktree> branch --show-current
git -C <worktree> status --porcelain --untracked-files=normal

It never writes files and never mutates git state.

License

MIT