UI & icon

Menu bar

• LSUIElement app: no Dock icon; status item uses custom NSImage.
• Merge Icons toggle combines providers into one status item with a switcher.
• Provider status items use stable autosave names and are reused across provider toggles so macOS can preserve icon positions.
• When Overview has selected providers, the switcher includes an Overview tab that renders up to 3 provider rows.
• Overview row order follows provider order; selecting a row jumps to that provider detail card.
• The global open-menu keyboard shortcut toggles the currently tracked menu closed before opening a new one.

Icon rendering

• 18×18 template image.
• Bar windows are provider/style-specific primary and secondary windows.
• Fill represents percent remaining by default; “Show usage as used” flips to percent used.
• Renderer/critter icons dim when last refresh failed and can render incident indicators; brand display mode uses provider branding plus title text.
• Loading animation runs at a bounded frame rate and has a hard continuous-duration ceiling so provider hangs cannot keep the menu bar redrawing forever.
• Display → Menu bar: menu bar can show provider branding icons with a percent label instead of critter bars.

Menu card

• Provider-specific rows with resets (countdown by default; optional absolute clock display). Primary, secondary, tertiary, and extra windows render when the provider snapshot has data for them.
• Codex credits can add a separate “Buy Credits…” menu action.
• Codex OpenAI web extras: code review remaining and usage breakdown render when dashboard data is attached.
• Token accounts: optional account switcher bar or stacked account cards (up to 6) when multiple manual tokens exist.
• Provider storage usage is opt-in from Advanced settings. When enabled, overview rows and provider detail cards can show local provider-owned storage totals, with a submenu for path breakdowns and copyable paths.

Pace tracking

Pace compares your actual usage against the expected consumption rate for the current window. Most providers use an even-consumption budget; Codex can use historical pace data when historical tracking is available.

• On pace – usage matches the expected rate.
• X% in deficit – you're consuming faster than the even rate; at this pace you'll run out before the window resets.
• X% in reserve – you're consuming slower than the even rate; you have headroom to spare.

When usage is in deficit, the right-hand label shows an estimated "Runs out in …" countdown. When usage will last until the reset, it shows "Lasts until reset".

Pace is currently calculated for supported Codex, Claude, OpenCode, and Abacus windows and is hidden when less than 3% of the window has elapsed.

Preferences notes

• Advanced: “Disable Keychain access” turns off browser cookie import; paste Cookie headers manually in Providers.
• Advanced: “Show provider storage usage” enables background scans of known provider-owned local paths; CodexBar only reports sizes and cleanup ideas, it does not delete files.
• Display: “Overview tab providers” controls which providers appear in Merge Icons → Overview (up to 3).
• If no providers are selected for Overview, the Overview tab is hidden.
• Providers → Claude: “Avoid Keychain prompts” uses the prompt-free Security CLI reader when available.
• The lower-level “Keychain prompt policy” picker only appears when the Security.framework reader is active.

Widgets (high level)

• Widgets render shared usage snapshots for the supported widget families and provider picker; detailed pipeline in docs/widgets.md.

See also: docs/widgets.md.