ANNULAR

§ Help

Help

How Annular works, what each thing on screen means, and how to remove it completely.

Install

Annular needs macOS 14 Sonoma or newer and a Mac with Apple Silicon. Open the DMG and drag Annular into your Applications folder. The app is signed and notarized by Apple, so it opens without a warning.

Annular has no Dock icon. It lives in the menu bar, and in a corner of your screen if you switch the corner widget on. To start it with your Mac, turn on Launch Annular at login in Settings, General.

Connect your Claude account

There are two ways, and you can use either.

  • Sign in with Claude opens Claude's own sign-in page in your default browser. Annular never sees your password. The sign-in grants two permissions, user:profile and user:inference, the same kind Claude Code receives. Annular uses them only to read your profile and your usage, and it never sends a prompt.
  • Use my Claude Code login reuses the login that Claude Code already keeps on this Mac. macOS asks you to allow Annular to read that Keychain item, and Always Allow means it asks only once. Annular only reads it and never changes it.

When Claude Code is signed in on this Mac and Annular has no sign-in of its own, Annular uses the Claude Code login by default, so macOS may show that Keychain question the first time you open the app. To switch this off, turn off Use the Claude Code login on this Mac when Annular has none in Settings, Account.

If the browser cannot hand the sign-in back to the app, choose Sign in with a code instead and paste the code the page shows you.

To disconnect, choose Sign Out in Settings, Account, or in the right-click menu. That deletes Annular's token from your Keychain. If you were using the Claude Code login, Sign Out stops Annular from using it. If you had signed in with Claude and Claude Code is also signed in on this Mac, Annular falls back to that login, unless the switch above is off. Claude Code's own login is never touched.

The menu bar item and the corner widget

The menu bar item shows the limit you are closest to, in its color. Click it to open the panel.

The corner widget shows every limit as a ring. Turn it on in Settings, General, then pick the corner, the size (Small, Medium, or Large), and the margin from the edge. With more than one display, a Display picker chooses the screen.

One of the two always stays on, so Annular can never disappear completely.

The panel

Hover over the widget to expand it, or click to pin it open. You can turn Expand on hover off in Settings, General.

Each limit gets one row: a bar, the time it resets, a forecast, and a small chart of recent use. Annular shows every limit Claude reports, usually three: your 5-hour session, your 7-day week across all models, and your 7-day week for a single model.

The forecast comes from your pace over the last hour. It reads either "At this pace: safe until reset" or the time you will reach 100 percent. It needs at least 10 minutes of history before it appears.

Colors and thresholds

A ring is teal when you are fine, amber from 50 percent, and coral from 75 percent. Change these in Settings, Thresholds, one limit at a time. Reset to Defaults brings the standard values back. The colors themselves come from the theme.

Notifications

Annular notifies you at 75 percent and at 90 percent, once for each limit in each reset period. In Settings, Alerts, you can change both numbers, switch alerts off for one limit, or switch them all off. You can also ask for a notification when a limit resets. Send Test Notification shows you what an alert looks like. Clicking a notification opens the panel.

Keep awake

The small square above the rings (beside them in the Strip theme, and a small circle in Minimal) keeps your Mac from going to sleep while a long job runs. The same switch is in the menu bar panel and in the right-click menu. Choose 15 minutes, 30 minutes, 1 hour, 2 hours, or until you turn it off. The shortcut is Option-Shift-K.

Keep awake stops idle sleep only. Your display can still sleep, and closing the lid on battery still puts the Mac to sleep. On battery it lets go by itself below 20 percent, and it is never switched back on when Annular restarts.

Themes

Settings, Appearance has six built-in themes: Annular, Editorial, Signal, Minimal, Strip, and Dial. Built-in themes cannot be changed, so choose Duplicate and Edit to make your own with a live preview. Themes are small JSON files with the extension .annulartheme. You can import and export them to share.

Shortcuts

  • Option-Shift-K turns keep awake on or off.
  • Option-Shift-H hides or shows the widget.
  • Option-Shift-U opens the usage panel.

Change any of them in Settings, Shortcuts.

What the captions mean

  • LOADING: Annular is fetching your usage for the first time.
  • SIGN IN: no account is connected.
  • STALE: the last refresh failed, so the rings dim and show the last numbers Annular has. Annular tries again by itself.

The next three appear only while Annular has no numbers to show yet.

  • OFFLINE: Annular could not reach the server, or the server answered with an error. It tries again by itself.
  • LIMITED: the server asked Annular to slow down. It waits and tries again by itself.
  • UNAVAILABLE: the server answered in a way Annular does not understand, or it did not accept your login.

A ring shows -- when there is no number to show yet.

Updates

Annular looks for an update once a day on annular.app, downloads it quietly, and installs it when you quit. Every update is checked against Annular's signing key before it installs. To check now, choose Check for Updates in Settings, About, or in the right-click menu. You can turn automatic checks off in Settings, About.

Where Annular keeps its data

  • Your sign-in: one item in the macOS Keychain, named Annular (service app.annular.oauth). It holds your token, the token that renews it, and your account email, organization, and plan. With the Claude Code login, Annular keeps no Keychain item of its own.
  • Usage history: ~/Library/Application Support/Annular/history.sqlite, kept for 90 days, and left out of Time Machine backups.
  • Your own themes: ~/Library/Application Support/Annular/Themes/.
  • Settings: ~/Library/Preferences/app.annular.plist.

To stop keeping history, turn off Keep usage history on this Mac in Settings, History. That also deletes what was stored. Purge History deletes it and keeps the setting on.

Uninstall

  • Sign out in Settings, Account, which removes the Keychain item.
  • Turn off Launch Annular at login in Settings, General.
  • Quit Annular and move it from Applications to the Trash.
  • Delete the folder ~/Library/Application Support/Annular.
  • Delete the file ~/Library/Preferences/app.annular.plist.

Get help

Write to support@annular.app. A person reads it.