---
status: open
tags:
  - wayfinder/map
---

# Pi UI customization

## Destination

Decide and specify a Pi TUI customization that reduces prompt-area dead space, consolidates footer information above the text prompt, represents context-window usage as a multi-colored bar, and exposes weekly ChatGPT Codex quota information if a reliable source exists.

## Notes

Plan first and preserve implementation for a later handoff unless a prototype ticket explicitly asks for throwaway local experimentation.
Prefer Pi extension APIs over patching Pi itself.
Finished customizations must be promoted through dotfiles rather than left as unmanaged files under `~/.pi/agent/extensions`.
The status bar should consolidate directory and branch, context-window usage, model, and thinking level.
The context-window bar should show total usage and, while under 90%, distinguish token categories when Pi exposes enough data.
Quota display must rely on an explicit API, local account source, or documented observable signal rather than scraping guesses.

## Frontier

- [[068-pi-ui-compact-status-extension-task]]
- [[070-pi-ui-flex-spacer-pi-patch-task]]

## Decisions so far

Pi extensions can replace the built-in footer and place a widget above the editor, so the compact prompt status idea can be prototyped without patching Pi.
Pi exposes total context-window usage through `ctx.getContextUsage()` and cumulative usage categories through session entries, but it does not expose a public exact breakdown of current context-window occupancy by content type.
Pi's docs and installed OpenAI Codex provider do not expose a documented proactive quota API, but third-party tools and OpenAI Codex source show a local first-party quota mechanism: ChatGPT/Codex usage endpoints plus Codex app-server `account/rateLimits/read` fallback.
The compact status prototype's preferred visual direction is above-prompt status with hidden footer, a visual directory/branch indicator, a thin full-width context bar, no context numbers, and the model/thinking label on the right.
The remaining prompt dead space is specifically an underfilled-stack issue: when transcript content is tall enough, the editor already reaches the bottom and looks good.
The prototype target is therefore a flexible spacer above the prompt/status/editor area, not a wholesale editor relocation.
The flex-spacer prototype received a positive HITL verdict and should be the preferred permanent layout direction.
Existing public prior art supports the patch direction: `pi-powerline-footer` shows the best extension-only compact status pattern, while `pi-local-mods` implements a private `FixedBottomScrollLayout` patch close to the desired bottom-pinned editor behavior.

## Not yet specified

The quota display prototype received a positive HITL verdict.
The permanent specification is complete in [[063-pi-ui-customization-spec-task]].
The implementation frontier includes [[068-pi-ui-compact-status-extension-task]].
The Pi patch implementation packaging was validated by [[073-pi-ui-community-pi-packaging-research]], which supports the package-override plan in [[072-pi-ui-patched-pi-packaging-research]].

## Out of scope

Replacing Pi's whole TUI or maintaining a fork of Pi is outside this effort unless research proves extension APIs cannot affect the target area at all.
