pi-footer-dock

A two-row status footer for Pi: Git, model, context, tokens, cache, speed, provider limits and cost, with explanations behind every value.

Packages

Package details

extension

Install pi-footer-dock from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:pi-footer-dock
Package
pi-footer-dock
Version
0.1.4
Published
Nov 14, 2026
Downloads
575/mo · 244/wk
Author
karan_khosla
License
Apache-2.0
Types
extension
Size
457.7 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "image": "https://raw.githubusercontent.com/KKhosla7/pi-footer-dock/main/docs/images/footer-wide.png",
  "video": "https://github.com/KKhosla7/pi-footer-dock/releases/download/media/footer-dock-launch.mp4",
  "extensions": [
    "./dist/index.js"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

Footer Dock

Check npm version npm downloads License: Apache-2.0 Node 22.19+ Pi 1.2 and 1.3 PRs welcome

https://github.com/user-attachments/assets/2f7eab93-210e-40e2-8736-d7cc64520ccc

The 30-second tour, also on YouTube.

A two-row status footer for Pi that tells you what is going on. Git, model, context, tokens, cache, speed, provider limits and cost, in two rows that fit your terminal, with an explanation behind every value.

Footer Dock on a wide terminal

Footer Dock on a narrow terminal

The footer chooses what to show for the width you have. Nothing is cut in the middle of a value: items drop out whole, least important first, and the project name goes last.

Install

pi install npm:pi-footer-dock

Then restart Pi (or run /reload). That is all. Full instructions, updating, removing and troubleshooting: SETUP.md.

Icons need a Nerd Font in your terminal. If the icons show up as empty boxes, your font does not have them: run /dock-glyphs for plain symbols that nearly every font has (/dock-glyphs again switches back), or install a Nerd Font. Footer Dock mentions this once, the first time it starts. On a Linux console, a dumb terminal or a terminal with a legacy character set it picks the plain symbols by itself; a choice in Appearance › Icons always wins.

What the footer shows

Item What it is Click the icon Click the text
Project folder Where Pi is working Opens it in your file manager Explains
Git branch The checked-out branch Lists branches; Enter prepares the switch Explains
Changed files Files with uncommitted changes Lists them; Enter shows the diff Explains
Commits ahead Commits not pushed yet Shows where Git is Explains
Model Provider and model Picks another model (with search) Explains
Thinking level The model's reasoning level Picks another level Explains
Context How much of the context window is used, and when Pi will compact Explains
Input, output Tokens used in this session Explains
Cache How much of the last prompt came from the provider's cache Explains
Speed Output tokens per second of the last response Explains
Limit usage What is left of the provider's 5-hour, weekly and monthly limits, with reset times Explains
Cost What this month (or week, day, session) would cost at API prices Explains

Every value explains itself

Click the text of any item. The explanation is a live screen, not a paragraph: it updates while it is open, scrolls with the wheel and the arrow keys, and always says what the value reports and when it can be missing.

The cache explanation

Limit usage shows, for each window, whether you are ahead of or behind the pace that would last until the reset, and what every marker means:

The limit usage explanation

Cost shows where the money went, by category and by model, and over days, weeks and months (press d, w or m):

The cost explanation

Look at your changes

Click the changed-files icon. Move with the arrows, search by typing, press Enter for the diff. The diff carries the line numbers the file has now, and lists the changed lines at the top, so you can find them in your editor.

Changed files

A diff with line numbers

The list and the diff look again every couple of seconds while they are open, so new changes appear by themselves.

Pick a model or a thinking level

Click the robot or the brain icon. Type to search, Enter to choose, Esc to close; the same icon closes it again.

Choosing a model

Settings

Run /dock-settings. Hide any item (at every width or only on narrow ones), choose which limit windows stay when the footer is tight, show limits as percent left or used, choose the period of the footer cost, switch icon sets, and more. Settings are saved in Pi's folder and shared by every Pi window.

The settings menu

Provider limits (off until you turn them on)

Some providers publish how much of a subscription is left (a 5-hour window, a weekly one, a monthly one). Footer Dock can show those windows with their reset times, and whether you are ahead of or behind the pace that would last until the reset. This is off by default: it needs a request you did not make, so you choose. With a supported provider and the setting off, the footer says limits off.

Supported providers

Provider Pi provider id Windows shown Asks (HTTPS)
ClinePass clinepass 5h, week, month api.cline.bot, /api/v1/users/me/plan/usage-limits
OpenCode Go opencode-go 5h, week, month opencode.ai, /zen/go/v1/usage
OpenAI Codex openai-codex the windows Codex reports chatgpt.com, /backend-api/wham/usage

Other providers show no limits (quota unsupported); OpenAI-style APIs that send rate-limit headers show those, which needs no extra request. Your provider is missing? Adding one is a small, self-contained change: see docs/adding-a-provider.md.

To turn it on: /dock-settings → Limit usage → Ask providers for limits → on.

What turning it on does: Footer Dock asks the provider's own usage service, at the address in the table, with the credential Pi already holds for that provider (obtained through Pi's public API; Footer Dock never reads credential files), at most once every 30 seconds across all your Pi windows. Nothing else is sent. These usage services are not documented as stable: if one changes, the windows disappear rather than being guessed. Turn the setting off and the requests stop at once.

Privacy and safety

  • No telemetry, no accounts, no servers of ours. Footer Dock makes no network request except the provider limit check above, and that only if you turned it on, only for the providers in the table.
  • Credentials: obtained from Pi at the moment of a request, sent only to the provider's fixed address, never stored, never logged, never shown.
  • Git is read-only and inert. Footer Dock only reads. It switches off every program a repository's own configuration could make Git run (core.fsmonitor, textconv, external diff, filters and so on), so opening a hostile repository cannot run code. It never switches branches itself: choosing a branch only prepares the git switch command in your message box for you to run.
  • Your history stays on your machine. The cost history is built from Pi's own session logs and cached under your user cache folder; only numbers and folder names are kept, never messages.
  • Files it writes: pi-footer-dock.json (settings) in Pi's folder, and a rebuildable cache under ~/.cache/pi-footer-dock. Both are private to your user.

Requirements

  • Pi 1.2 or newer, and Node.js 22.19 or newer (the same as Pi).
  • A terminal with mouse support for clicking (everything also works from the keyboard and with /dock-* commands). A Nerd Font gives the best icons; /dock-glyphs switches to plain symbols.
  • Tested on Linux. macOS and Windows are expected to work; opening the project folder with the system file manager has not been run on them yet.

Commands

Command What it does
/dock-settings The settings menu
/dock-info [item] Explains a footer item
/dock-quota Shows or hides the collapsed limit windows
/dock-open Opens the project folder in your file manager
/dock-open-with ... Chooses another app for that, for example thunar {path}
/dock-glyphs Switches between Nerd Font icons and plain symbols
/dock-color ... Footer colours and bold icons, for example accent #aa55cc
/dock-refresh Reads Git and usage again
/dock-config ... Session-only footer configuration as JSON
/dock-debug Safe diagnostics for a bug report (no content, no secrets)

Large repositories

The Git items watch the repository for changes. If a repository is too large to watch (thousands of directories), Footer Dock falls back to reading Git after each Pi action and says so in the item's explanation; it never shows a number it did not read.

Other extensions' status lines

Extensions that show a status with Pi's setStatus keep working: Footer Dock shows those texts on one extra line at the bottom, exactly where Pi's own footer would, and the line is absent while nothing sets a status. Extensions that want proper places, settings and explanations register with Footer Dock instead (next section).

For other extensions

Extensions can have Footer Dock manage their footer items, settings and explanations, and Footer Dock needs to know nothing about them: see docs/extending-footer-dock.md.

Contributing

Footer Dock is open source (Apache License 2.0) and contributions are welcome, small ones included.

  • Found a bug, or have an idea? Open an issue. For a bug, paste the output of /dock-debug: it holds counters and settings only, no messages, no secrets and no paths.
  • Want to change something? Send a pull request. Fixes, tests and documentation improvements can go straight to a pull request; for a new feature or a new data source, open an issue first so we can agree what it should do. CONTRIBUTING.md explains how to set up, what the checks are, and what to keep in mind.
  • Writing an extension? Let Footer Dock draw its footer items: docs/extending-footer-dock.md.
  • Found a security problem? Please report it privately, see SECURITY.md.

By contributing you agree that your work is licensed under the same Apache License 2.0; there is no contributor agreement to sign.

CONTRIBUTING.md · SECURITY.md · CHANGELOG.md · LICENSE