---
status: complete
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

None.

## 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.
The compact status extension is implemented as a managed Pi extension with an above-editor status widget, hidden footer, context/quota bars, and `/codex-quota`.
The flex-spacer Pi patch is implemented as a dotfiles-managed package override in commit `5fd8de0`, with manual visual verification left for the final deployment verification ticket.
The deployed ordinary Pi command now combines the compact status extension and patched bottom-anchored prompt layout, with autocomplete closing back to bottom alignment and no unmanaged prototype extension loaded.

## Not yet specified

None.

## 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.