pi-status

Context bar compositor and LLM environment injector for Pi. Owns the context-bar widget at the top of the TUI, renders live session info, and injects a small environment block into the system prompt before each agent run.

I built this because Pi's default status display was minimal, and I kept needing to check the model, token usage, and git branch manually while working. This pulls all of that into one persistent bar that other extensions can also write into.

Install

pi install npm:@pedro_klein/pi-status

What it provides

• Context bar widget — persistent TUI bar showing model, token usage, I/O stats, thinking level, and git branch
• External segment API — other extensions register and update named segments in the bar via pi events
• LLM environment injection — appends git branch, context percentage, and worktree warning to every agent system prompt
• Footer — renders cwd, keybinding hints, and any extension status messages at the bottom of the TUI
• Title — keeps the terminal title updated with model, mode (if pi-modes is active), and git branch

Context Bar Segments

Built-in segments render in priority order (highest first):

Segment	Priority	Shows
_model	90	Current model name (shortened)
_tokens	80	Token usage bar + percentage + count
_io	70	Cumulative session input/output tokens and cost
_thinking	60	Thinking level with color coding
_branch	10	Current git branch

External Segment API

Other extensions can add or update segments in the context bar using Pi's event system:

// Register a new segment (call once at setup)
pi.events.emit("pi-status:register", {
  id: "my-segment",      // unique ID
  priority: 50,          // higher = further left; default 50
  render: (theme) => theme.fg("muted", "my text"),
});

// Update an existing segment's content
pi.events.emit("pi-status:update", {
  id: "my-segment",
  render: (theme) => theme.fg("accent", "updated text"),
});

// Remove a segment
pi.events.emit("pi-status:update", {
  id: "my-segment",
  render: null,
});

The render function receives the Pi theme object and returns a string (with ANSI color via theme.fg(color, text)).

Priority controls left-to-right ordering: _model (90) is leftmost, _branch (10) is rightmost. External segments default to priority 50 (between _io and _thinking).

LLM Environment Injection

Before each agent run, pi-status appends to the system prompt:

Git branch: main
Context: 24% used (48k/200k tokens)

If multiple worktrees are active, a warning is added:

⚠ 3 worktrees active — verify correct worktree before making changes.

This keeps the model aware of where it is without you having to say it.

Configuration

No configuration required — works out of the box.

The extension automatically skips itself when running inside a Pi subagent process (PI_SUBAGENT_DEPTH > 0) to avoid duplicate status bars in nested agent runs.

Development

pnpm test           # run tests
pnpm build          # build for publish
pnpm typecheck      # type-check without emitting

License

MIT