# pi-hud

HUD-style footer for [pi-coding-agent](https://github.com/badlogic/pi-mono),
inspired by [claude-hud](https://github.com/jarrodwatts/claude-hud).

Replaces pi's default footer with a **bordered editor** + single-line status
footer. The input box gets a rounded, left-aligned status border on top and
bottom, and pi's footer slot shrinks to one stats line.

## Layout

**Top border (rounded) — runtime state**

```
╭── π [model] [thinkingLevel] · phase · ponytail · goal ────────╮
```

**Input rows** — wrapped with `│` on each side; the first row carries an
inline `❯ ` prompt (wrapped rows pad to the same text column).

**Bottom border (rounded) — session identity**

```
╰── [cwd] · [git:branch] · [duration] ──────────────────────────╯
```

**Footer (single line) — stats**

```
Q0 | ctx ████░░░░ 45% (12.3k|200k) | $0.023 | ↑12k ↓2k | ↻ R W | Δcost
```

| Field      | Source                                  | Notes                                          |
| ---------- | --------------------------------------- | ---------------------------------------------- |
| model      | `ctx.model.id`                          | `provider/id` from active session              |
| cwd        | `ctx.cwd`                               | truncated to last 2 segments if longer than 36 |
| git branch | `footerData.getGitBranch()`             | reactive via `onBranchChange`                  |
| duration   | session start timestamp                 | ticks every 30s                                |
| context %  | `ctx.getContextUsage()`                 | bar colored green/yellow/red at 70/85          |
| cost       | walk `sessionManager.getBranch()`       | sums `usage.cost.total`                        |
| tokens     | same walk                               | input + output, `↑` `↓` arrows                 |
| last tool  | `tool_execution_start` event            | shown for 30s after the tool finishes          |
| goal       | `goal_updated` event (pi-goal)          | 🎯 <objective> on line 1; ⏸ when paused, ⚠ when budget-limited; hidden when complete/dropped |

## Slash command

```
/hud            # toggle
/hud on         # force enable
/hud off        # disable
/hud reload     # re-read config.json
```

Default state: enabled on first install.

## Configuration

Create `~/.pi/agent/pi-hud/config.json` to toggle individual fields:

```json
{
	"enabled": true,
	"showModel": true,
	"showCwd": true,
	"showContext": true,
	"showCost": true,
	"showGit": true,
	"showDuration": true,
	"showLastTool": true,
	"showGoal": true,
	"contextWindowOverride": 1000000
}
```

See `config.example.json` in this folder.

### Context window override

`pi-hud` discovers the model's window size through this fallback chain:

1. `ctx.getContextUsage().contextWindow` (Pi's runtime value)
2. `ctx.model?.contextWindow` (Pi's model metadata)
3. `contextWindowOverride` from your `config.json`
4. `200_000` (last-resort default)

For models that aren't registered in Pi's `models-store.json` (e.g. **MiniMax-M3**, which isn't listed even though you're using it), steps 1 and 2 will fall back to Pi's default. Set `contextWindowOverride` to the model's true context window so the `ctx %` bar reads accurately.

After editing the config, run `/hud reload`.

## How it works

- Lives at `extensions/pi-hud/index.ts`, loaded by pi's `jiti` runtime — no build step
- Calls `ctx.ui.setFooter(factory)` to take over the bottom status slot
- The factory captures the active `ctx` (session context) and recomputes the
  display on `requestRender()` — triggered by:
  - Git branch changes (via `footerData.onBranchChange`)
  - Wall-clock tick every 30s (duration timer)
  - Any other event that invalidates the footer (typed input, tool events)
- `/hud off` calls `ctx.ui.setFooter(undefined)` to restore pi's default footer
- Self-disabling safety: if `config.enabled === false` during a render, the
  factory calls `setFooter(undefined)` and the default returns cleanly

## Limitations (v0.1)

- Two lines only. No tool-activity list, subagent tracker, todos, rate limits,
  or compaction counter — those require either more event subscriptions or
  parsing transcript files (modeled on claude-hud's stream parser)
- One fixed layout (no presets like claude-hud's Full / Essential / Minimal yet)
- Cost only accumulates from completed assistant messages on the current
  branch
- 30s wall-clock tick is best-effort; in suspended terminals `setInterval`
  may stall

## Roadmap (v0.2+)

- [ ] Presets: `essential` / `expanded` / `compact` via `/hud preset <name>`
- [ ] Tool-activity row (running, completed, with counts)
- [ ] Subagent tracker (model, description, elapsed time)
- [ ] Compactions counter (from `agent_end` w/ `reason: "compact"`)
- [ ] Cache hit-rate display (`usage.cache.read/write`)
- [ ] Optional title-bar companion extension for tmux / Ghostty users
- [ ] CJK-aware width handling (already delegates to `visibleWidth`)