pi-hud

A pi package extension that provides the ambient HUD framework — a vessel for injecting a small briefing block into the model's context on every LLM call. pi-hud carries no built-in sections itself; all content comes from other extensions contributing via the shared EventBus.

This is a port of the "HUD" pattern (see botwithmemory's <mira:hud>), adapted to stock pi and stripped of its one expensive habit: persisting the HUD into the transcript. In pi, the HUD is non-persistent — it lives only in the per-call message copy and never enters stored history.

What it does

• Refreshes on agent start, assistant messages, and tool execution end. The HUD is rebuilt at the start of each user prompt, after every assistant message completes, and after each tool execution ends. This keeps the HUD ≤ one tool call stale mid-agentic-run.
• Injects on every LLM call via the before_provider_request event, which fires right before the HTTP request leaves for the provider. The HUD is inserted as a synthetic assistant/tool-call pair directly into the payload's messages array. This is purely outbound mutation — nothing touches the persisted transcript, so there is zero accumulation and zero compaction tax.
• Adds zero transcript clutter. Nothing returned from before_provider_request is written to the session. Old HUDs don't recede into history — they simply don't exist next call. There is no accumulation cost, no compaction tax, and no footprint the user has to wade through.
• Is hidden from the user. No widget, no transcript entry, nothing in the TUI. The HUD is exclusively for the model's ambient awareness. Set PI_HUD_DEBUG=1 to log the injected payload to stderr for verification.

The injected block

The HUD is injected as a synthetic assistant/tool-call pair — not free-text to echo back:

{ assistant: { tool_calls: [{ id: "hud_...", type: "function", function: { name: "__hud", arguments: "{\"Time\":\"...\",\"Context\":\"...\",\"CWD\":\"~\"}" } }] },
  tool:   { tool_call_id: "hud_...", content: "ok" } }

The arguments field contains structured JSON with one key per contributed section (label → value). Sections returning null are omitted entirely. If all sections return null, no HUD is injected.

Placement

The HUD is always appended at the absolute tail of the messages array. It uses the assistant/tool role pair, which is provider-legal everywhere and avoids role-order issues.

No cache markers are emitted. KV cache on the stable prefix is preserved by construction: the HUD mutates only the tail, leaving all stable history byte-identical. The HUD tokens are uncached by necessity (the content changes every refresh) — you can't both cache a block and have it update.

System prompt injection

The model understands what <pi:hud> blocks are because a brief description is injected into the system prompt on before_agent_start — no inline framing text needed in the HUD itself.

Controls

| Flag | Effect | |------|--------| | --no-hud | Disable injection entirely. |

| Env | Effect | |-----|--------| | PI_HUD_DEBUG=1 | Log the injected HUD payload to stderr before each LLM call. |

Install

pi install /path/to/pi-hud
# or, for a quick test:
pi -e /path/to/pi-hud

As an auto-discovered project extension under .pi/extensions/pi-hud/ it loads after project trust; /reload hot-reloads it.

Contributing sections from other extensions

All HUD content comes from other extensions contributing via the shared EventBus. A contributing extension emits a hud_section event; pi-hud collects it and renders it on every HUD rebuild.

How it works

1. A contributing extension emits { id, label, render } onto pi.events during its factory init.
2. pi-hud subscribes to that event and buffers contributions in a Map keyed by id.
3. On every HUD rebuild (agent_start, message_end, tool_execution_end), each contributed section is rendered fresh via its render(ctx) function, processed sequentially in registration order.

If pi-hud isn't installed, emissions silently do nothing — no coupling required.

Example

// In any extension's factory:
export default function(pi: ExtensionAPI): void {
  pi.events.emit("hud_section", {
    id: "memory-state",
    label: "Memory",
    async render(ctx) {
      const entries = await ctx.sessionManager.getCustomEntries("memory");
      if (!entries?.length) return null;
      return `${entries.length} entries loaded`;
    },
  });
}

The result appears in the HUD JSON as:

{"Memory":"12 entries loaded"}

Contract

| Field | Type | Description | |-------|------|-------------| | id | string | Unique key. Duplicate IDs: last wins (warning logged). | | label | string | Shown as the JSON key, e.g. "Memory", "Tasks". | | render(ctx) | (ExtensionContext) => Promise<string \| null> \| string \| null | Called fresh on every HUD rebuild. Return null to omit the line. May be async. |

Error handling

• Render throws: caught per-section, line omitted, error logged (debug mode only). One bad section doesn't kill the whole HUD.
• Slow async render: 2-second timeout per section. Timed-out sections are omitted.
• Duplicate IDs: last registration wins; warning emitted to stderr in debug mode.

Files

• index.ts — event wiring, refresh triggers, injection.
• sections.ts — HudSection interface + sequential renderer with per-section timeout.
• compose.ts — pure HUD block assembler (JSON serialization).
• package.json — pi manifest.

Why no persistence

botwithmemory persists each turn's HUD as a real assistant message, so old HUDs recede into history ("prior states remain visible"). That costs a full HUD of tokens per turn until compaction folds them. In stock pi, ctx.sessionManager is read-only for extensions, so persistence isn't available anyway — but even where it is, non-persistent injection is the cleaner default: identical live-awareness benefit, zero accumulation. The "prior states visible" property is only worth the tax if the model actually consults stale HUDs, which is an open empirical question.