Ai Usage Rings

AI Usage Rings

[](https://github.com/ojasviyadav/ai-usage-rings/actions/workflows/ci.yml)

Activity-style rings for your Claude Code and Codex weekly usage limits, in the macOS menu bar, on the desktop as widgets, and on a paired iPhone.


Everything runs on your Mac. A small background collector reads the limits through the official CLIs every 15 minutes, stores them locally, and serves them to the app on loopback. It never sends a model message, so watching your usage does not consume it.

What it shows

• Up to three ordered rings. The first selected subscription is the outer ring. Each ring fills as the weekly budget is used.
• Menu bar. The icon is a live mini preview of the rings. Click it for remaining percentages and reset countdowns.
• Desktop widgets. Small, medium, and large WidgetKit sizes with the same ring order and colors.
• iPhone. A companion app with Home Screen and Lock Screen widgets, paired with a QR code over your local network.
• Evidence, not estimates. Each reading keeps the exact text the CLI printed, its capture time, and a confidence flag. Stale readings are dimmed. A failed poll is shown as a typed failure, never as a guessed number.

Supported sources

Source	How it is read	Model turns
Claude Code	The built-in /usage command in a locked-down local terminal session	0
Codex (ChatGPT Codex and Work limits)	codex app-server and the account/rateLimits/read request	0

General ChatGPT message limits are not supported. That is a permanent scope decision.

Requirements

• macOS 15 or later on Apple Silicon.
• The Claude Code CLI, the Codex CLI, or both, signed in.
• iOS 18 or later for the optional iPhone companion.

Intel Macs are not supported because the bundled collector is built for Apple Silicon only.

Install

Th