# pi-worktree-tui-status

A **TUI-only** worktree and experiment status indicator for [Pi](https://pi.dev/).

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

```text
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.

```text
🌳 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:

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

```bash
pi install npm:pi-worktree-tui-status
```

Try without installing:

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

Local development:

```bash
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:

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

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

### Bash commands

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

```bash
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:

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

Examples:

```text
🌳 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:

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

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

## Package contents

The npm package includes only:

```text
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:

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