[FEATURE] macOS Widget for usage

[PatrickHeneise]

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I often need to go into the Claude app settings just to check my current model usage and understand where I am in my session, daily, or weekly token limits. Doing this repeatedly breaks my flow, especially during longer coding sessions where I want to stay focused in my editor.

Because usage information isn’t easily visible, it’s hard to build an intuitive sense of how much capacity I have left at any given moment. I sometimes only realize I’m close to a limit when I’m already deep into a task, which can lead to unexpected interruptions or the need to stop and re-plan work mid-stream.

Proposed Solution

I'd like a “Claude Usage” widget from the macOS widget gallery and keep it visible in Notification Center or on my desktop. At a glance, it shows my current session, daily, and weekly token usage using simple progress indicators and percentages.

The widget updates automatically as I use Claude, so I can passively track usage while working without opening the app. If I want more detail, clicking the widget opens the Claude app directly to the usage view.

The experience feels lightweight and native—usage awareness is always available when I need it, but never interrupts my workflow.

Alternative Solutions

There's no API endpoint for usage available, according to Claude

Priority

Medium - Would be very helpful

Feature Category

Other

Use Case Example

1.	I’m in a focused coding session using Claude Code for reviews and refactors.
2.	Before making a large or expensive request, I glance at the macOS widget to see my session and daily usage.
3.	I notice I’m getting close to my daily limit.
4.	Based on that, I adjust my prompt to be more targeted or ask for a shorter response.
5.	Later, the widget shows I’m near the limit, so I decide to save heavier usage for later.
6.	If I need more detail, I click the widget to open Claude directly to the usage view.

Additional Context

No response

[Pringled]

Hey @PatrickHeneise I was actually looking for the same thing today and found https://github.com/steipete/CodexBar, might be what you're looking for.

[PatrickHeneise]

Thanks @Pringled!

[JanSuthacheeva]

A simpler approach that would enable this (and other integrations like waybar, polybar, tmux statusline, etc.) would be a --usage CLI flag:

claude --usage

Output as JSON for easy parsing:

{
  "session": {"percent_used": 6, "resets_at": "2025-01-30T10:59:00+07:00"},
  "week": {"percent_used": 7, "resets_at": "2025-02-04T13:59:00+07:00"},
  "week_sonnet": {"percent_used": 5, "resets_at": "2025-02-04T13:59:00+07:00"}
}

This matches the three metrics displayed in the interactive /usage command:

• Current session (all models)
• Current week (all models)
• Current week (Sonnet only)

This would be more general than a macOS-specific widget and allow users to build their own integrations. Currently there's no way to get this data programmatically:

• /usage only works in interactive mode
• Piping /usage to claude -p returns "Unknown skill: usage"
• Making separate API requests uses different auth context and wastes quota