[Feature] feat: Add token and quota usage display at the bottom of the CLI (inspired by Claude Code)

[Felixqaq]

What does this PR do?

This PR introduces a real-time token and quota usage display at the bottom of the terminal during an active oh-my-codex session. The UX is heavily inspired by Claude Code, providing a clean and non-intrusive way to monitor API consumption directly within the CLI.

Why is this change needed?

Currently, users have limited visibility into their API costs and token consumption while running tasks in Codex. By surfacing this information directly in the footer (HUD), developers can effortlessly track their usage and remaining quota without breaking their workflow or needing to log into the provider's dashboard.

Key Changes

• Usage Tracker: Added logic to extract and accumulate token metrics (prompt_tokens, completion_tokens, total_tokens) from the API response payload.
• CLI Footer UI: Implemented a persistent status bar at the bottom of the terminal to display the current session's usage and quota details.
• Rendering Adjustments: Updated the terminal rendering loop to ensure the usage display anchors securely to the bottom and does not interfere with the main conversational output or long-running workflows like $team and $plan.

[Yeachan-Heo]

Thanks — this is a reasonable feature direction, but it is not a trivial drop-in because quota semantics differ a lot across providers and not every runtime exposes a reliable remaining-quota signal in-session.

Concrete next step for this request: we should scope it first as session-local usage metrics (prompt/completion/total tokens when available), and treat provider quota/remaining budget as a separate follow-up rather than bundling both into one HUD feature.

Leaving this open as a feature request with that narrower framing.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]

[Jah-yee]

Implementation Suggestion

Great feature idea! Here are some suggestions for implementation:

Token Display Format

Consider showing formatted numbers for readability:

function formatTokenCount(value: number): string {
  if (value >= 1\_000\_000) return `${(value / 1\_000\_000).toFixed(1)}M`;
  if (value >= 1\_000) return `${(value / 1\_000).toFixed(1)}k`;
  return `${value}`;
}

Placement Options

• Bottom-fixed bar: Use terminal escape codes to anchor to bottom
• Toggle with hotkey: Allow users to show/hide with Ctrl+B or similar
• Configurable: Add to .omx/hud-config.json for user preference

Metrics to Track

Based on HudMetrics interface in src/hud/types.ts:

• session_input_tokens, session_output_tokens, session_total_tokens
• five_hour_limit_pct and weekly_limit_pct for quota visibility

Existing Code to Leverage

The src/hud/render.ts already has rendering logic that could be extended. The renderGitBranch() pattern shows how to create sanitized output.

Would love to see this landed! 🎯

[Yeachan-Heo]

Useful suggestions, but I want to keep the scope tight so this doesn't balloon into an ambiguous HUD/quota project.

The right first slice here is still:

• session-local usage metrics only
• prompt / completion / total tokens when the runtime actually exposes them
• no provider-specific remaining quota / budget promises in the first pass

Things like bottom anchoring, toggles, config surface, and quota percentages are follow-up design choices, not the minimum acceptable scope for v1.

So I'm keeping this open under that narrower framing: show reliable in-session token usage when available; treat quota/remaining budget as a separate problem.

—
[repo owner's gaebal-gajae (clawdbot) 🦞]