Support writing stdin rate_limits to a local JSON snapshot file

[YoungsunLi]

Hi! First, thanks for building Claude HUD — it’s been really useful.

I’d like to request a small feature that seems very aligned with the current architecture:

Request

When Claude Code provides rate_limits via stdin, optionally write that data to a local JSON snapshot file as well.

Claude HUD already has a read-side integration for external usage snapshots:

• display.externalUsagePath
• display.externalUsageFreshnessMs

So this would basically be the symmetric write-side of that idea:

• read rate_limits from official stdin
• write a small JSON snapshot locally
• no OAuth/API polling
• no undocumented endpoints
• no change to the current usage source of truth

Why this would help

I’m currently building a small AI tool and I’d love to read Claude HUD’s usage/rate-limit data directly instead of reimplementing the same parsing / snapshot logic myself.

In other words, I don’t want to reinvent the wheel if Claude HUD is already the component closest to the official stdin data.

Suggested behavior

Something like an optional config field could work well, for example:

• display.externalUsageWritePath
• or display.writeExternalUsagePath

And then when rate_limits is present on stdin, Claude HUD writes a JSON snapshot like:

{
  "updated_at": "2026-05-12T08:00:00.000Z",
  "five_hour": {
    "used_percentage": 42,
    "resets_at": 1747036800
  },
  "seven_day": {
    "used_percentage": 18,
    "resets_at": 1747600000
  }
}

This seems like a very small, low-risk feature because:

• the data already exists in stdin
• Claude HUD already knows how to consume a similar snapshot format
• it would not reintroduce any API/OAuth/compliance concerns
• other local tools could reuse the same snapshot

Important constraint

I’m not asking for Claude HUD to fetch usage from any separate API or credentials source.

Only:

• if official rate_limits exists in stdin,
• optionally persist it to disk.

I think this would make Claude HUD a nice local source of truth for the broader Claude Code tooling ecosystem.

Thanks for considering it.

[jarrodwatts]

Thanks for the clear request. This fits the existing external-usage snapshot direction, and I labelled it as an enhancement.

A safe implementation should be opt-in, write atomically, and avoid writing on every statusline render tick. It should persist only official stdin rate_limits fields and avoid API polling or credential reads. I am keeping this open for backlog/design.