Rinco Pi HUD

A dynamic HUD footer for Pi.

Features · Installation · Usage · Customization · Development

简体中文

Rinco Pi HUD provides a rich, real-time status footer for Pi TUI sessions. It displays project state, Git metrics, runtime versions, session activity, model usage, token costs, and more — all in a responsive four-group or customizable single-line layout. Pi loads the TypeScript extension directly, so no build step is required (tsconfig.json sets noEmit: true and is used only for npm run typecheck).

Features

• Project state — Working directory, Git branch, commit, tag, status, operation state, diff metrics, and runtime versions.
• Session activity — Model, provider, context usage, independently controlled input/output tokens, cache, session cost, turn count, and thinking level.
• Tool and agent activity — Independent controls for running tools, completed tool counts, active agents, idle state, skills, and MCP server status.
• Model quota — Automatic Codex weekly quota or Token Switch balance display by model provider.
• Git awareness — Branches, detached HEAD, tags, ahead/behind, stash, merge/rebase conflicts, and dirty state.
• Runtime detection — Node, Python, Go, Rust, Java, and 60+ other runtimes with package version parsing.
• Configurable layout — Responsive Project, Session, Activity, and Usage groups by default, or fully customizable single-line templates.
• Granular status controls — Toggle Git operation state, tool runtime/counts, active/idle agents, and input/output tokens separately from /zentui.
• Extension statuses — Reads third-party extension statuses and places them by configurable position and color mode.
• Safe fallback — Graceful timeout and error handling; no stale data after session shutdown.

Installation

Install from npm (recommended)

pi install npm:rinco-pi-hud

The published package is available on npm.

Install from GitHub

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

Install from a local checkout

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.

Usage

Restart Pi after installation, or run:

/reload

The HUD footer is enabled by default. Run /zentui to open the interactive settings UI.

Common commands

/zentui statusline enable
/zentui statusline disable
/zentui statusline toggle
/zentui row project toggle
/zentui row session disable
/zentui row activity enable
/zentui row usage toggle
/zentui format clear
/zentui format "$model · $context · $cost · $git_branch( $git_commit) · $session_duration"
/codex-status
/usage-refresh

[!NOTE] For the best result, use a Truecolor terminal and a Nerd Font. The footer uses Unicode glyphs that render best with proper font support.

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, token switch, and 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 test suite (41 tests across 8 files)

Customization

Layout

The default layout groups Project, Session, Activity, and Usage information. Long groups wrap at complete segment boundaries with aligned continuation lines. Set footerFormat to a template string for a single-line layout:

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

Template variables use $name or ${name} syntax. See the footer reference for the complete variable list.

Segments

Open /zentui, then select Built-in segments to enable or disable individual statuses. Fine-grained controls include:

Group	Independently controlled statuses
Project	Git status, Git operation state (MERGING, REBASING, etc.), commit, metrics, runtime, package, OS, and user
Session	Model, thinking level, turn count, and duration
Activity	Running tools, completed tool counts, active agents, Agent idle, skills, and MCP
Usage	Context, input tokens, output tokens, cache details/hit rate, cost, quota, and time

Existing configs using the former aggregate tokens, toolActivity, or agentActivity switches are migrated automatically. The whole footer can still be controlled with /zentui statusline enable|disable|toggle.

In the default four-row layout, each semantic row can also be controlled directly:

/zentui row <project|session|activity|usage> <enable|disable|toggle>

Row switches are persisted in footerRows. They do not affect a custom single-line footerFormat.

Extension statuses

Third-party extensions publish statuses that the HUD footer can display. Configure placement (left, middle, right, off) and color mode (zentui, original) for each extension status key.

Development

Prerequisites

• Node.js 22.19 or later
• Pi

Install development dependencies:

npm install

Available commands

Command	Description
npm test	Run the complete Vitest suite once.
npm run test:watch	Run Vitest in watch mode and retest when files change.
npm run typecheck	Run TypeScript type checking with tsc --noEmit.
npm run pack:check	Inspect the publishable package with npm pack --dry-run without publishing it.

Run the test suite:

npm test

Check types:

npm run typecheck

Verify formatting, types, lint rules, tests, and package contents:

npm run verify
npm run pack:check

Vitest covers footer layout, telemetry, codex usage, token switch, config counts, and MCP status parsing. Pi loads the TypeScript source directly, so this project has no separate build command.

Troubleshooting

The footer does not appear

1. Confirm that Pi is running in TUI mode rather than headless, JSON, or print mode.
2. Run /reload or restart Pi.
3. Run pi list to confirm that the package is installed.

The footer layout looks wrong

The footer auto-detects terminal width and truncates content. In narrow terminals, some segments may be clipped. Adjust the layout by setting a custom footerFormat template, or disable low-priority segments in /zentui.

Colors look incorrect

Make sure your terminal supports Truecolor. The footer emits 38;2;r;g;b ANSI sequences.

Unicode icons are missing or misaligned

Unicode and Nerd Font glyphs vary between terminals and fonts. Install a Nerd Font, or switch to ASCII icon mode via /zentui.

Third-party licenses

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

• pi-zentui by Luka — MIT licensed. The Footer portion was adapted for this package.
  Source: https://github.com/lmilojevicc/pi-zentui
• pi-shannon-statusline by RealAlexandreAI — MIT licensed. Session, model, activity, MCP, configuration-count, and Codex subscription capabilities were adapted.
  Source: https://github.com/RealAlexandreAI/pi-shannon-statusline
• pi-codex-usage by narumiruna — MIT licensed. The Codex usage client under extensions/hud/telemetry/codex-usage/ derives from this project.
  Source: https://github.com/narumiruna/pi-codex-usage

See NOTICE for details.