# pi-worktree-tui-status

This package is intentionally tiny and **TUI-only**.

## Handoff context

This project was created because the user's issue workflow creates git worktrees under:

```text
runs/agents/worktrees/<slug>
```

The user's experiment-mode workflow also creates disposable runs under:

```text
runs/experiments/<product-or-app>/<slug>
```

The user **does not change Pi's cwd** into those folders. Instead, the agent works autonomously by editing long paths and by running commands like:

```bash
git -C runs/agents/worktrees/<slug> status --short
python runs/experiments/<product-or-app>/<slug>/run.py
```

Therefore, normal statusline extensions that inspect only `ctx.cwd` are not enough. This extension detects the active worktree or experiment from the **paths used in tool calls and shell commands**, then shows a small TUI status segment.

Expected display:

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

## Hard non-goals

Do **not** expand this into a worktree manager.

- Do not create worktrees.
- Do not switch/check out branches.
- Do not remove/prune worktrees.
- Do not redirect Pi tools.
- Do not sandbox bash.
- Do not write files.
- Do not mutate git state.
- Do not add PR/merge automation.
- Do not create, promote, archive, or clean up experiments.

This is only a visual status indicator.

## Architecture

- `index.ts` — single-file Pi extension.
- `test/index.test.ts` — pure function tests for path and bash parsing.
- `README.md` — user-facing docs and npm package description.
- `package.json#files` intentionally publishes only the minimal extension/docs.

## Detection behavior

Primary detection is path-convention based:

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

It inspects:

- Tool call fields: `path`, `cwd`, `file`, `directory`, `target`.
- Bash command strings from tool calls.
- User shell commands from `user_bash`.
- `git -C <path>` patterns.
- Other shell tokens containing `runs/agents/worktrees/<slug>` or `runs/experiments/<product-or-app>/<slug>`.

There is also a fallback that detects existing linked worktrees outside the convention by comparing:

```bash
git rev-parse --path-format=absolute --git-dir
git rev-parse --path-format=absolute --git-common-dir
```

If they differ, the path is inside a linked worktree.

## Pi APIs used

- `pi.on("tool_call", ...)` to inspect tool arguments.
- `pi.on("user_bash", ...)` to inspect user shell commands.
- `pi.on("session_start" | "agent_end" | "session_shutdown", ...)` for lifecycle cleanup/refresh.
- `ctx.ui.setStatus()` for the TUI status segment.
- `pi.exec("git", ["-C", root, ...])` for read-only branch/dirty state.

## Read-only git commands allowed

The extension may run only read-only git commands, currently:

```bash
git -C <worktree> branch --show-current
git -C <worktree> status --porcelain --untracked-files=normal
git -C <path> rev-parse ...
```

Do not add commands that mutate git state. Experiment detection should remain path-only and must not create, write, delete, or promote experiment artifacts.

## Development commands

Use Node 22+.

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

Current validation status at handoff: `npm run validate` passes.

## Local testing in Pi

From this directory:

```bash
pi -e ./index.ts
```

Then cause the agent or shell to touch a worktree path, for example:

```bash
git -C runs/agents/worktrees/example status --short
```

The status segment should update if that path exists as a git worktree, or at least show `checking…` immediately for convention-matching paths.

## Release checklist

```bash
npm run validate
npm publish --access public
```

Before publishing, confirm `npm pack --dry-run` includes only expected files:

```text
AGENTS.md
CHANGELOG.md
LICENSE
README.md
index.ts
package.json
```

## Naming rationale

The name is deliberately explicit:

```text
pi-worktree-tui-status
```

It must stay clear that this package is for **TUI status only**, not worktree administration.