pi-hud

HUD-style footer for pi-coding-agent, inspired by 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:

{
	"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)