Claude Usage Widget for macOS

A native macOS widget that lets you keep an eye on your Claude Code usage limits — right from your desktop.

If you're anything like me, you've made Claude Code part of your daily workflow. And if you're on a usage-capped plan, you know the feeling: you're deep in a coding session, everything is flowing, and then — rate limit. Session over. Go touch grass.

This widget fixes that. It sits quietly on your desktop (or in Notification Center) and shows you exactly where you stand — daily and weekly — with color-coded progress rings that go from green to orange to red as you approach your limits. It even counts down to your next reset, so you can plan your sessions accordingly.

The clever part: it reads your actual Claude Code session logs from ~/.claude/projects/, parses the token usage from every assistant response, and aggregates it in real time. No API key needed. No manual tracking. It just knows.

Built entirely with SwiftUI and WidgetKit. No Electron. No web views. Just a clean, native macOS widget that feels right at home next to your Weather and Calendar widgets.

Features

• Real usage data — Parses your actual Claude Code session logs for token counts
• Progress rings — Visual at-a-glance usage for daily and weekly limits (e.g. "15.1M / 45M")
• Color-coded — Green when you're good, orange when you should pace yourself, red when you're close
• Reset countdown — Know exactly when your limits refresh
• Two sizes — Small (compact rings) and Medium (rings + progress bars + details)
• Dark mode — Adapts automatically to your system appearance
• Auto-refresh — LaunchAgent updates data every 5 minutes; widget refreshes every 15 min or at reset
• Multiple data sources — Local session scanning, JSON file, or remote API endpoint

Getting Started

Requirements

• macOS 14.0 (Sonoma) or later
• Xcode 15+ (to build)
• XcodeGen (brew install xcodegen)

Build & Install

# Clone
git clone https://github.com/coastalnotes/claude-usage-widget.git
cd claude-usage-widget

# Generate Xcode project
./generate_project.sh

# Open in Xcode
open ClaudeUsageWidget.xcodeproj

In Xcode:

1. Select both targets and set your Signing Team (a free Apple ID works)
2. Update DEVELOPMENT_TEAM in project.yml with your Team ID for CLI builds
3. Build & Run (Cmd+R)
4. Right-click your desktop > Edit Widgets > search "Claude"

Set Up Auto-Refresh

The included Python script scans your Claude Code session logs and writes usage data that the widget reads. Install the LaunchAgent to keep it updated automatically:

./Scripts/install_launchagent.sh

This runs Scripts/update_usage.py every 5 minutes. You can also run it manually anytime:

python3 Scripts/update_usage.py

Customizing Limits

Default limits are set to 45M tokens/day and 225M tokens/week. Adjust for your plan:

python3 Scripts/update_usage.py --daily-limit 30000000 --weekly-limit 150000000

Data Sources (in priority order)

The widget tries these sources in order:

1. ~/.claude/claude_usage.json — Written by the update script (recommended)
2. App Group container — If you configure a shared container
3. Remote API — Configure an endpoint URL in the app
4. Direct session scan — Falls back to parsing ~/.claude/projects/ JSONL files directly

The JSON format is straightforward:

{
  "daily": {
    "used": 15112664,
    "limit": 45000000,
    "resetsAt": "2026-04-06T00:00:00+00:00"
  },
  "weekly": {
    "used": 15112664,
    "limit": 225000000,
    "resetsAt": "2026-04-07T00:00:00+00:00"
  },
  "lastUpdated": "2026-04-05T19:30:00+00:00"
}

Project Structure

ClaudeUsageWidget/              # Main app — configuration UI
  App/                          # App entry point + settings view
  Models/                       # UsageData, UsageBucket (token formatting)
  Services/                     # Multi-source data provider
  Shared/                       # Colors and theming

ClaudeUsageWidgetExtension/     # Widget extension
  Views/                        # ProgressRingView, Small + Medium layouts
  Provider/                     # WidgetKit timeline provider

Scripts/
  update_usage.py               # Parses ~/.claude session logs → JSON
  install_launchagent.sh        # Sets up 5-min auto-refresh

How It Was Built

This entire project — every Swift file, the widget UI, the data layer, the session log parser, the Xcode project configuration, the LaunchAgent, all of it — was built with Claude Code. From the initial architecture to the final xcodebuild that produced a signed .app, it was a conversation.

That's kind of the point of this widget: it exists because Claude Code is useful enough that you want to know how much of it you have left.

Contributing

This started as a personal tool, but PRs are welcome. Some ideas:

• Large widget size with historical usage chart
• Menu bar app variant
• Direct integration with Anthropic's API when a usage endpoint becomes available
• Automatic limit detection based on plan tier

License

MIT — do whatever you want with it.