Pi Task Monitor

Always-on-top real-time task monitor for Pi.

Preview

┌───────────────────────────────────────────────────────────────────────┐
│ ◀ ▶ ● Pi Task Monitor  1/N                                📌  —  ✕   │
├───────────────────────────────────────────────────────────────────────┤
│                               RUNNING                                 │
│                   ▶ edit relative/path/to/file.py                     │
├───────────────────────────────────────────────────────────────────────┤
│ 🧠 provider-a 🔒  ·  claude-opus  ·  high  │  In 801  Out 875  │ ...  │
└───────────────────────────────────────────────────────────────────────┘

Install

pi install npm:@dianel/pi-hud

After installation, restart Pi. The monitor window appears in the top-left corner.

Features

• Multi-session aware — switches between multiple Pi terminal sessions
• Multi-monitor safe — validates the saved window position against the current virtual desktop and recenters it when a monitor is disconnected or the layout changes
• Provider-aware model display — maps the model requested in the session to the matching model configured for that provider, with safe fallback to the runtime value
• Reload-safe — /settings reload or Pi restart automatically refreshes the HUD
• OAuth indicator — 🔒 shown when the current provider has valid login credentials
• Session navigation — ◀ ▶ buttons or keyboard shortcuts to browse sessions
• Responsive layout — footer switches between one and two rows; horizontal resizing preserves the current UI scale, while vertical resizing keeps status and command content centered
• Context visibility — resolves the active model's context window from Pi's custom and built-in model catalogs
• Task activity — shows a colored, enlarged, shaking bell while Pi is running
• Subagent cost — keeps Pi's session total aligned with the native footer and shows recognized subagent-tool cost as a separate breakdown

Shortcuts

| Shortcut | Action | | ---------- | -------- | | Drag title bar | Move window | | Drag edges / corners | Resize; horizontal dragging preserves the current UI scale | | ◀ / Ctrl+[ | Previous session | | ▶ / Ctrl+] | Next session | | Session label | Click to toggle auto-follow mode | | Ctrl+T | Toggle always-on-top | | Ctrl+A | Toggle transparency | | Ctrl+H | Minimize window | | Ctrl+Q | Quit |

Session display

| Label | Meaning | |-------|---------| | ● auto | Auto-following latest active session | | 1/N | Manually viewing session (N = running Pi terminals) |

Responsive behavior

• The footer uses one row when its content fits and two rows when it wraps; its icons stay aligned with the scaled text baseline.
• Long command text stays on one line so it cannot grow the panel's minimum height; the full command remains available in the Pi terminal.

Footer fields

| Segment | Color | Description | | --------- | ------- | ------------- | | Provider 🔒 | Blue | Current LLM provider (🔒 = valid OAuth login) | | Model | Cyan | Current model name | | Thinking | Purple | Reasoning intensity | | In / Out | Green | Token usage this turn | | HitCache | Orange | Cache hit rate | | Ctx | Blue | Latest turn token usage as a percentage of the active model's context window | | Cost | Amber | Pi session total, with recognized subagent-tool cost shown as a separate breakdown |

Status

• RUNNING — Pi is active and the latest tool call is visible
• THINKING — Pi is active without a visible tool call
• IDLE — Pi has settled and is waiting for input

How It Works

The ESM extension registers Pi lifecycle hooks. On start it registers the current terminal and starts pi_hud.py only when the shared monitor is not already alive. The Python side tails the latest Pi session JSONL file and reads settings / models for live status, rendering a compact Tkinter overlay. Multiple Pi terminals share this one monitor process through a PID registry; it exits only after the last registered terminal is gone.

On reload, the Node extension reuses the existing monitor and only removes its own terminal registration, so another terminal cannot make the shared panel disappear.

Context calculation

Ctx divides the latest assistant usage total by the active provider/model context window. The displayed model is resolved within the active provider before the context window lookup. The context window lookup order is:

1. ~/.pi/agent/models.json, including modelOverrides
2. Pi's built-in ~/.pi/agent/models-store.json
3. Optional manual compatibility entries in ~/.pi/model_config.json

Manual model mapping

Automatic mapping is provider-scoped and uses the actual provider/model from the session. For runtime aliases that cannot be inferred automatically, create the optional ~/.pi/model_config.json:

{
  "mappings": {
    "provider-a": {
      "gpt-5.6-luna-max": "gpt-5.6-luna"
    }
  },
  "contextWindows": {
    "provider-a": {
      "gpt-5.6-luna-max": 272000
    }
  }
}

mappings and contextWindows are both keyed by provider and then the runtime model. A manual mapping takes precedence over automatic catalog mapping. The file is optional, ignored when missing or invalid, and is not included in the package.

Themes

Right-click the monitor and open theme to choose Dark, White, or Paper Beige. The selection is saved with the window geometry and restored on the next launch.

Data sources

| Display | Source | | --------- | -------- | | Current command | Session JSONL — latest assistant toolCall | | Provider / Model | Session JSONL provides the actual provider/model request; the displayed model is normalized against that provider's models.json / models-store.json catalog | | Thinking level | Session JSONL — thinking_level_change event | | Token usage | Session JSONL — assistant message usage | | Main / subagent cost | Main-session usage, all tool-result usage, and compaction/branch-summary usage; recognized subagent-tool cost is shown separately | | Activity status | Session JSONL — agent_start / agent_settled lifecycle events | | OAuth status | ~/.pi/agent/auth.json — provider credential expiry | | Context window | models.json → models-store.json → ~/.pi/model_config.json |

Manual start (development)

python pi_hud.py

License

MIT