@pi-vault/pi-status

Replace Pi's default footer with a compact, configurable status line that shows the session details you actually care about. @pi-vault/pi-status installs a live footer, adds /statusline for interactive configuration, and optionally surfaces usage-backed limits through @pi-vault/pi-usage.

Default footer:

model-with-reasoning · current-dir

Screenshots

Default status line rendering:

Interactive configuration editor (/statusline):

Install, Upgrade, And Reload

Install or upgrade the extension:

pi install npm:@pi-vault/pi-status

Optional: install pi-usage if you want the five-hour-limit and weekly-limit footer segments:

pi install npm:@pi-vault/pi-usage

Reload Pi after installing or upgrading:

/reload

Usage-limit segments depend on pi-usage. /statusline can show those segment options after pi-usage responds, and the live footer renders them when compatible live limit window data is available.

Quick Start

Once installed, the footer updates automatically.

• Run /statusline inside Pi to open the interactive editor.
• Toggle segments on or off with Space.
• Reorder enabled segments with Left and Right.
• Search the segment list by typing.
• Preview the footer before saving.
• Hide individual extension status keys from the "Extension statuses" section.
• Save changes and reuse them the next time Pi starts.

While the editor is open, the live footer is temporarily hidden so the inline UI can use the full width cleanly.

Available Segments

You can compose the footer from these segment IDs:

• model
• model-with-reasoning
• project-name
• current-dir
• git-branch
• run-state
• context-remaining
• context-used
• used-tokens
• total-input-tokens
• total-output-tokens
• session-id
• five-hour-limit
• weekly-limit

five-hour-limit and weekly-limit depend on standalone @pi-vault/pi-usage. /statusline shows those segments after pi-usage responds, and the live footer omits them until compatible live limit window data is available.

Extension Status Behavior

Extension statuses are no longer configured as a normal footer segment.

• Status text reported by other Pi extensions is appended automatically when it is visible.
• /statusline lets you hide individual status keys.
• Hidden keys stay hidden through persisted settings.
• If no visible extension statuses remain, nothing extra is appended to the footer.

Common Examples

Keep it minimal:

model-with-reasoning · current-dir

Show more session detail:

model · run-state · git-branch · context-used · context-remaining · session-id

Usage-aware footer:

model-with-reasoning · current-dir · five-hour-limit · weekly-limit

If another extension reports status text, that text appears after your configured segments automatically, for example:

model-with-reasoning · current-dir · alpha: ready

Configuration Behavior

@pi-vault/pi-status reads settings from both Pi settings locations:

• global: ~/.pi/agent/settings.json
• project: .pi/settings.json

Project statusLine values override global statusLine values when both exist.

When you save from /statusline, pi-status writes back to the project settings file if that file already owns the statusLine key. Otherwise it writes to the global settings file.

Upgrade Notes For 0.2.x Users

If you are upgrading from 0.2.x, note these compatibility changes:

• context-window-size and extension-statuses are no longer supported segment IDs.
• Existing configs that still mention removed IDs are normalized by dropping those unsupported entries.
• Extension status visibility now comes from per-key hidden status settings instead of a dedicated extension-statuses segment.
• Global and project statusLine settings still merge, with project values overriding global values.
• The extension now requires Node.js >=24.15.0.
• The tested Pi host baseline is now @earendil-works/[email protected] and @earendil-works/[email protected].

Development And Verification

pnpm install
pnpm check
pnpm run pack:dry-run

License

MIT