# 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:

```bash
pi install npm:pi-universal-hud
```

Or pin a specific version:

```bash
pi install npm:pi-universal-hud@0.1.2
```

Then reload Pi:

```text
/reload
```

or restart Pi.

To remove it:

```bash
pi remove npm:pi-universal-hud
```

## Local development install

For local development, install directly from this folder:

```bash
pi install /Users/user/universal-hud
```

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

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

Then reload:

```text
/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:

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

Example:

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

## Pi package manifest

This package follows Pi package conventions via `package.json`:

```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

```bash
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:

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

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

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

Release checklist:

```bash
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:

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

After publishing, users install with:

```bash
pi install npm:pi-universal-hud
```

For a scoped package:

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

## Notes for this machine

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

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

The active development package is:

```text
/Users/user/universal-hud
```