Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Latest commit

 

History

10 Commits

Folders and files

Repository files navigation

Claude Usage

A native macOS menu bar app that shows your live Claude Code usage — 5-hour and 7-day windows, per-model breakdowns, extra usage credits, and optional MQTT publishing.

Screenshots

Usage Settings MQTT
Usage Settings MQTT
Live usage bars with reset countdowns, extra usage in dollars Polling interval and 30+ menu bar icon options Optional MQTT publishing to any broker

Features

  • 5-hour window utilisation and reset countdown
  • 7-day window with per-model splits (Opus, Sonnet)
  • Extra usage credits vs. monthly limit in dollars
  • Configurable menu bar icon (30+ SF Symbols)
  • Configurable polling interval (5m / 10m / 15m / 30m / 1h)
  • Optional MQTT publishing to any broker (Home Assistant, etc.)
  • Right-click the menu bar icon to quit
  • Re-login button when tokens expire — opens Claude Code in Terminal
  • Debug log viewer built in

Prerequisites

  • macOS 14+
  • Claude Code CLI installed and signed in:
    brew install claude-code
    claude
    The app reads the OAuth token that Claude Code stores in your Keychain (Claude Code-credentials).

Install

From source

  1. Open ClaudeUsage.xcodeproj in Xcode
  2. Build (Release)
  3. Copy to Applications:
    cp -R ~/Library/Developer/Xcode/DerivedData/ClaudeUsage-*/Build/Products/Release/ClaudeUsage.app /Applications/
  4. Launch:
    open /Applications/ClaudeUsage.app

Run on startup

  1. Open System Settings > General > Login Items
  2. Click + and select /Applications/ClaudeUsage.app

Usage

Click the menu bar icon to see your current usage. The app polls the API automatically at the configured interval (default 10 minutes). Click the refresh button to force an update.

If you see a token error, click "Open Claude Code (type /login)" to re-authenticate — this opens Claude Code in Terminal where you type /login.

MQTT

Navigate to Settings > MQTT Publishing to configure a broker. The app publishes the usage JSON to your chosen topic after every successful API poll. Useful for Home Assistant dashboards, display kiosks, etc.

How it works

UsageService reads the Claude Code-credentials Keychain entry (written by the claude CLI), extracts the OAuth access token, and calls GET https://api.anthropic.com/api/oauth/usage with the oauth-2025-04-20 beta header. If the token expires (401), it attempts a refresh using the stored refresh token.

The User-Agent: claude-code/<version> header is required — without it, the API applies aggressive rate limiting.

MQTTClient.swift is a zero-dependency MQTT 3.1.1 publisher built on Apple's Network framework.

Caveats

  • Uses Anthropic's usage endpoint which is unofficial and may change without notice.
  • The app reads (and may refresh) Claude Code's OAuth tokens in the Keychain. Don't distribute this to anyone you don't want accessing your usage data.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages