pi-minimal-footer

An opinionated, compact, one-line status bar for Pi.

Left

• Working directory: ~/git/project
• Git branch:  main ↑2 ↓1 (↑ to push, ↓ to pull)

Right

• Extension statuses:  🧠 Karpathy  🪽 Icarus
• Model: model
• Context usage: 42/200k
• Subscription usage bar with reset time: [⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h

Install

Requires Node.js >=22.19.0. Interactive terminal UI only.

Choose one npm name (they contain the same extension; do not install both):

pi install npm:pi-minimal-footer
# or
pi install npm:@ryu-cz/pi-minimal-footer

The scoped package is an official mirror, not a separate extension.

Commands

Command	Action
/minfooter	Toggle footer
/minfooter on	Enable
/minfooter off	Disable

Settings

Edit minFooter in Pi's agent settings.json (normally ~/.pi/agent/settings.json). All defaults are shown below. Apply edits with /reload or /minfooter on.

{
  "minFooter": {
    "enabled": true,
    "showGitBranch": true,
    "showSkills": true,
    "showPath": true,
    "showModel": true,
    "showContext": true,
    "powerlineSeparator": true,
    "gitRefreshSeconds": 91,
    "gitFetch": false,
    "gitFetchTimeoutSeconds": 17,
    "maxUsageBarCells": 10
  }
}

• showSkills shows extension status text, not installed skills. The footer does not add the example statuses itself.
• Set powerlineSeparator to false for plain spaces instead of  /  if your font lacks those glyphs. The git icon  and sync arrows also need compatible glyphs; hide Git data with showGitBranch: false if needed.
• gitRefreshSeconds: local refresh interval; 1–2147483 seconds; default 91.
• gitFetch: background fetch on startup, then roughly 5 minutes after each attempt completes; failures are silent; default false.
• gitFetchTimeoutSeconds: fetch timeout; 1–2147483 seconds; default 17. Invalid timer settings use their defaults.
• maxUsageBarCells caps the Braille bar length (excluding brackets and reset time). Use a positive integer, e.g. 4 for a compact bar; invalid values fall back to 10.

Reading the footer

Git

Counts require a configured upstream. Unsynced branches use normal text color; synced branches are dim. Count changes pulse the whole Git section bold for one second; further changes restart the pulse.

Context

42/200k means tokens used / context window. ? means Pi has not reported usage yet, including immediately after compaction.

Subscription usage

[⣿⣿⣿⣤⠀⠀⠀⠀⠀⠀]↻1d8h shows subscription allowance used, not context usage.

• Bar: expands into spare space, using 2–10 cells by default, capped by maxUsageBarCells. Smaller caps and very narrow terminals may show fewer cells or only the reset label.
• Colors: green below 85%, amber from 85%, red from 92%.
• Cached data: dim after a refresh failure.
• Reset: local ↻HH:mm through 24 hours; whole days/hours above 24 hours (↻1d8h); whole days above 10 days (↻12d). Remaining durations round down. No reset reported means bar only.
• Shows the shortest available usage window for the selected provider. Missing credentials, unsupported/local models, or absent limits hide the usage bar. Custom proxy endpoints are not polled.
• Virtual/routed models show model and context usage, but no subscription bar.

Adapters

Adapters use Pi's existing credentials; ordinary Claude API keys do not expose subscription usage.

Authenticated endpoints remain unverified live; see verification limits.

Implemented adapters:

• OpenAI Codex
• Claude OAuth
• GitHub Copilot
• Gemini CLI
• MiniMax
• Kimi Coding
• OpenCode Go

Extension statuses

Provided by other extensions; hidden with showSkills: false. Narrow terminals may shorten or omit them.

Only one footer extension can be active. For plugin integration, see VISION.md.

Programmatic control

Other Pi extensions can enable or disable the footer for the current session without changing saved settings:

pi.events.emit("pi-minimal-footer:set-enabled", { enabled: false }); // disable
pi.events.emit("pi-minimal-footer:set-enabled", { enabled: true });  // enable

• Events work only while this extension's session is active.
• The latest command or event wins.
• /minfooter on/off saves your preference into config; events don't.
• Enabling may replace another footer.
• Disabling restores Pi's default footer if this footer is active; it leaves another extension's active footer untouched.
• New sessions and /reload use your saved preference.

Development & design

Install from source:

pi install git:github.com/Ryu-CZ/pi-minimal-footer

Developer guide: VISION.md. Release history: CHANGELOG.md.

Credits

Provider usage-fetching and parsing logic copied and adapted from Can Celik (@ogulcancelik)'s pi-minimal-footer. Upstream MIT attribution is retained in extensions/lib/LICENSE.