pi-worktree-tui-status

A TUI-only worktree status indicator for Pi.

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

runs/agents/worktrees/<slug>/...

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

𖠰 issue-1234-fix-camera | ⎇ 1234-fix-camera | dirty +3

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 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

Example:

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

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

Display

The extension writes one Pi status segment:

𖠰 <slug> | ⎇ <branch> | <clean | dirty +N | dirty ?>

Examples:

𖠰 issue-workflow-fix | ⎇ 1943-improve-issue-workflow | clean
𖠰 roi-camera-plan | ⎇ 2110-roi-camera-plan | dirty +4

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

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.

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. It only 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