claude-quota: macOS Menu Bar Gauges for Claude Code Usage

Overview

claude-quota is a macOS menu bar utility designed to track the usage quotas of Claude Code. It utilizes a SwiftBar plugin to display visual gauges that represent the 5-hour window utilization and weekly limits for one or more Claude accounts directly in the macOS menu bar.

Key Features and Visual Indicators

The tool provides immediate visual feedback on quota status through color-coded bars and countdown timers:

  • 5-Hour Window Utilization: The menu bar shows a gauge for each account. The color changes based on usage: green for low usage, orange for $\ge 70%$, and red for $\ge 90%$.
  • Reset Countdowns: When the 5-hour window is fully exhausted, the gauge is replaced by a countdown timer (e.g., 4:28) indicating the time remaining until the quota resets.
  • Weekly Limit Alerts: If the weekly limit is reached, the bar turns black and displays a countdown to the weekly reset (e.g., 2D), which overrides the 5-hour window status.
  • Detailed Dropdown: Clicking the menu bar gauge opens a dropdown containing comprehensive details for every account, including 5-hour and weekly windows, per-model windows (where reported), extra-usage credits, and specific reset times.
  • Refresh Rate: The plugin refreshes every 5 minutes automatically, with a manual "Refresh now" option available in the dropdown.

Technical Implementation

claude-quota operates by reading the Claude Code OAuth token from the macOS Keychain in a read-only capacity. It then queries the internal, undocumented usage endpoint used by the Claude Code /usage screen.

Because the tool does not refresh or rewrite tokens, it cannot log the user out of their accounts. The author notes that because the endpoint is undocumented, future changes to Claude Code may require updates to the plugin.

Installation and Configuration

Installation

Users can install the tool via a curl script or by cloning the repository:

Quick Install:

curl -fsSL https://raw.githubusercontent.com/grzegorz-raczek-unit8/claude-quota/main/install.sh | bash

Manual Install:

git clone https://github.com/grzegorz-raczek-unit8/claude-quota.git
cd claude-quota
./install.sh

Both installation methods automatically set up SwiftBar if it is not already installed via Homebrew. Users must select "Always Allow" when the macOS Keychain permission dialog appears during the first refresh.

Account Management

By default, the plugin auto-discovers accounts by scanning ~/.claude and ~/.claude-* configuration directories that have corresponding Keychain entries.

  • Labeling: A single account is displayed without a label. Multiple accounts are labeled by the directory suffix (e.g., ~/.claude-work becomes W).
  • Customization: Users can pin or rename accounts by creating a ~/.config/claude-quota/accounts file with one path [label] per line.
  • Visibility: Accounts can be hidden from the menu bar gauge while remaining in the dropdown details via the ~/.config/claude-quota/hidden file or the "Hide from menu bar" option in the dropdown.

Community Discussion and Alternatives

Community feedback on Hacker News highlights a variety of alternative tools for tracking AI usage quotas. While claude-quota focuses on the macOS menu bar, other users suggested tools that integrate directly into the terminal or the Claude Code status line.

Alternative tools mentioned by the community include:

  • CodexBar and usage4claude: Tools that support multiple providers, including Codex.
  • ClaudeCodeStatusLine: A plugin that adds usage data directly into the Claude Code interface.
  • codeburn, claudebar (for Linux/Hyprland), and RateLimited.

Some users expressed a preference for this data to be natively integrated into the Claude Code status bar, noting that a simple percentage of the weekly quota remaining would be significantly more useful than external plugins.

Sources