Pi Universal HUD

Universal HUD is a Pi package that provides a Claude-HUD-style statusline/footer for Pi.

Features

• Model, thinking level, project, session, and timer line
• Context usage bar
• Codex 5h / weekly usage windows
  • Reads ~/.codex/sessions/**/rollout-*.jsonl first
  • Falls back to Codex telemetry logs when rollout data is unavailable
• Tool and agent activity summaries
• Claude HUD terminal ANSI palette colors and glyph progress bars
• /uhud, /universal-hud, /uhud-mode, /uhud-layout, and /uhud-config commands
• ctrl+shift+u toggle shortcut and ctrl+alt+u layout shortcut

Install from npm

After this package is published to npm, install it in Pi with:

pi install npm:pi-universal-hud

Or pin a specific version:

pi install npm:pi-universal-hud@0.1.2

Then reload Pi:

/reload

or restart Pi.

To remove it:

pi remove npm:pi-universal-hud

Local development install

For local development, install directly from this folder:

pi install /Users/user/universal-hud

If you previously installed the npm package, remove it first to avoid duplicate HUD instances:

pi remove npm:pi-universal-hud
pi install /Users/user/universal-hud

Then reload:

/reload

Commands

Command	Description
/uhud	Toggle Universal HUD
/universal-hud	Toggle Universal HUD
/uhud-mode expanded	Use expanded layout
/uhud-mode compact	Use compact layout
/uhud-mode statusline	Render below editor
/uhud-mode footer	Replace footer
/uhud-layout expanded|compact	Set layout only
/uhud-config	Show config path and current config

Configuration

Runtime HUD config is stored at:

~/.pi/agent/state/universal-hud.json

Example:

{
  "enabled": true,
  "surface": "footer",
  "lineLayout": "expanded",
  "pathLevels": 1
}

Pi package manifest

This package follows Pi package conventions via package.json:

{
  "keywords": ["pi-package"],
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

Pi loads the TypeScript extension source directly through its extension runtime, so src/index.ts is included in the npm package.

Development

cd ~/universal-hud
npm install
npm test
npm run check

Publish to npm

Before publishing, make sure the package name in package.json is the npm name you want:

{
  "name": "pi-universal-hud"
}

If you want a scoped package, rename it before publishing, for example:

{
  "name": "@your-scope/pi-universal-hud",
  "publishConfig": {
    "access": "public"
  }
}

Release checklist:

cd ~/universal-hud
npm install
npm test
npm run check
npm pack --dry-run
npm login
npm whoami
npm publish --access public

For later releases:

npm version patch   # or minor / major
npm publish --access public

After publishing, users install with:

pi install npm:pi-universal-hud

For a scoped package:

pi install npm:@your-scope/pi-universal-hud

Notes for this machine

The previous single-file extension was disabled and kept as a backup:

~/.pi/agent/extensions/universal-hud.ts.disabled

The active development package is:

/Users/user/universal-hud