omp packages

rinco-pi-hud1.4.0

A dynamic HUD footer for Pi, ported from Sakura Zentui Footer.

GitHub Actions Published 2 days ago MIT ~727 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Did it work for you?

Result

One report per person. A new report replaces your old one.

Reports 0

No reports yet.

Readme

Rinco Pi HUD

A live status footer for Pi. Project, git, session, tool and cost state in four groups, updated while you work.

Pi package TypeScript Tests License

Install · Commands · What it shows · Layout · Development

简体中文

The Rinco Pi HUD footer inside Pi: a Project row with directory, git branch and Node version, a Session row with provider and model, an Activity row with tool counts, and a Usage row with context window, tokens, cache hit rate and cost.

Rinco Pi HUD takes over Pi's footer with four groups of live state and lets you switch off anything you do not want. Pi loads the TypeScript extension directly, so there is no build step: tsconfig.json sets noEmit: true and exists only for npm run typecheck.

Install

Requires Pi 1.3.0 or newer within the 1.x release line. Development and CI dependencies are pinned to 1.3.0.

pi install npm:rinco-pi-hud

Restart Pi afterwards, or run /reload. The footer is enabled by default and /zentui opens the settings UI.

From GitHub, or from a local checkout:

pi install git:github.com/Rinisnotarobot/rinco-pi-hud

git clone https://github.com/Rinisnotarobot/rinco-pi-hud.git
cd rinco-pi-hud
pi install "$PWD"

[!IMPORTANT] Pi extensions run with your user permissions. Review the source before installing any third-party extension.

[!NOTE] Truecolor and 256-color terminals are supported; explicit RGB colors use Pi's terminal-capability-aware encoder. The screenshot above renders with ASCII icon mode; /zentui switches between the auto, nerd, and ascii glyph sets.

Commands

Command Effect
/zentui Settings UI: rows, segments, separator, icons, colors, templates
/zentui statusline enable|disable|toggle Show or hide the whole footer
/zentui row project|session|activity|usage <enable|disable|toggle> Turn one row on or off
/zentui format "<template>" Replace the four rows with a single-line template
/codex-status Print Codex subscription usage and rate-limit windows
/usage-refresh Refresh the model usage or balance shown in the footer

What it shows

Row Segments, each with its own switch under Built-in segments in /zentui
Project directory, git branch, commit and tag, working-tree status, operation state (MERGING, REBASING, …), diff metrics, runtime, package version, OS, user
Session session name, provider and model, thinking level, turn count, duration
Activity running tools, completed tool counts, active agents, Agent idle, skills, MCP servers
Usage context window with a gauge, input and output tokens, cache read/write volume and hit rate, cost, model quota, clock

Rows are toggled with /zentui row usage disable; the segments inside them have individual switches in the same UI. Existing configs that used the former aggregate tokens, toolActivity, or agentActivity switches are migrated automatically.

Model quota

The Usage row follows the active model's provider:

  • openai-codex — ChatGPT subscription rate limits and reset credits, queried through Pi auth with a codex app-server fallback. Reads as codex 60% 5h (14:30) 75% wk; the reset stamp becomes 14:30 12 Feb when the window rolls into another day.
  • token-switch — billing balance from the TOKEN_SWITCH_API_KEY environment variable, as token-switch $750.00.
  • deepseek — account balance from the DeepSeek API using the credential Pi holds for the provider, either from /login or DEEPSEEK_API_KEY. Reads as deepseek ¥110.00, preferring CNY when the account reports several currencies.

These queries use a 15-second timeout and a 5-minute cache, and /usage-refresh refreshes the active one on demand.

Layout

The same footer rendered at 72 and 56 columns: rows wrap between segments, continuation lines realign under the separator column, and a tool-count segment that cannot fit is shortened with an ellipsis while the segments after it still render.

Groups wrap only at segment boundaries. A continuation line realigns under the separator column, and a segment that no longer fits is shortened with … instead of pushing the segments after it off the row.

Set a template for a single-line footer instead of the four groups:

/zentui format "$cwd( $git_branch)$fill($context)( $tokens)( $cost)"

Variables accept $name or ${name}. The footer reference lists all of them, along with the aliases ($directory, $status, $codex, …). Run /zentui format with no argument, or /zentui format clear, to go back to the four groups.

Configuration

/zentui writes to ~/.pi/agent/rinco-pi-hud.json and applies changes immediately. It covers the separator style, icon mode (nerd, ascii, or auto), footer colors (Pi theme tokens or terminal palette styles), context rendering (text, gauge, or both), the project refresh interval, and third-party extension statuses with their own placement and color mode.

See docs/footer.md for the full variable and segment reference.

Project contents

Path Purpose
extensions/hud/index.ts Composition root for controllers, shared state, and UI installation
extensions/hud/config/ Configuration model, normalization, migration, and persistence
extensions/hud/footer/ Footer rendering, semantic grouping, responsive layout, and template parsing
extensions/hud/segments/ State collectors: Git, runtime, MCP, skills, projects, etc.
extensions/hud/telemetry/ Usage formatting, provider balance probes, and the Codex subscription client
extensions/hud/session/ Pi event registration, session lifecycle, and live context overlay
extensions/hud/state/ Aggregated state, telemetry reducer, and project refresh controller
extensions/hud/commands/ /zentui settings UI and configuration controller
extensions/hud/ui/ Icons and terminal style utilities
docs/footer.md Complete footer configuration reference
docs/CONTRIBUTING.md Local development, testing guidance, and pull request checklist
tests/ Vitest suite: footer layout, telemetry, provider balances, MCP configuration counts

Development

Node.js 22.19 or later, and Pi itself.

npm install
npm test          # Vitest suite
npm run typecheck # tsc --noEmit
npm run verify    # format, types, lint, tests

Every script is defined in package.json; docs/CONTRIBUTING.md lists them all, including lint, format, and test:watch.

README images

The two boards above are generated from a real footer render rather than drawn by hand. assets/readme/source/capture-footer.mts drives the extension's own installFooter path over this repository's state and a real Pi session transcript, then build-assets.mts turns the ANSI rows into SVG:

npx tsx assets/readme/source/capture-footer.mts . ~/.pi/agent/sessions/<session>.jsonl 118 72 56 > /tmp/footer.json
npx tsx assets/readme/source/build-assets.mts /tmp/footer.json

Troubleshooting

The footer does not appear

Confirm Pi is running in TUI mode rather than headless, JSON, or print mode. Then run /reload, and pi list to confirm the package is installed.

The layout looks wrong in a narrow terminal

The footer measures the terminal and wraps at segment boundaries, so narrow windows show fewer segments per line. Set a footerFormat template, or disable low-priority segments in /zentui.

Colors look incorrect

The default RGB palette follows Pi's detected terminal color mode, with 256-color approximation when needed. Check terminal capability settings and try the theme color source in /zentui.

Icons are missing or misaligned

Unicode and Nerd Font glyphs vary between terminals and fonts. Install a Nerd Font, or switch to ASCII icons in /zentui.

License

MIT. See LICENSE.

Third-party licenses

This package incorporates work from the following open-source projects:

See NOTICE for details.