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 Claude

Annular has no sign-in of its own. It reads Claude through Claude Code, and from version 1.2 on it reads Codex through Codex. One of the two must be installed and logged in on this Mac, and you can use both. For Claude there are two ways, and you can use either or both.

  • Use my Claude Code login reads the login that Claude Code already keeps on this Mac. From version 1.2.2 on Annular reads it through Apple's own security tool, the way Claude Code reads it, so macOS does not ask you about it: the button, and the switch in Settings, Sources, are your yes. Earlier versions read the Keychain item themselves, and macOS asked for your Mac password again every few hours, each time Claude Code renewed its login; updating ends that. Annular only reads it, never changes or renews it, and keeps no token of its own. Annular never sees your password, uses the login only to read your usage, and never sends a prompt. In those earlier versions, if you answered no, Annular asked once and then left it. In every version you can switch the reading off and on in Settings, Sources.
  • The status line feed follows Claude Code's documented status line and needs no Keychain access. Switch it on in Settings, Sources. Annular shows you the exact change to Claude Code's settings first, keeps a copy of your settings file when there is one, and keeps your own status line running unchanged. The rings then move the moment Claude Code replies. The feed knows your session and your week, not the week of a single model. Claude Code does not send these numbers for every kind of login, and when yours has none, Settings, Sources says so.

Without Claude Code and without Codex on this Mac, Annular says so and shows three steps to set Claude Code up. That window notices by itself when Claude Code or Codex is there.

Connect Codex

From version 1.2 on, Annular can read your Codex limits. When Codex is on this Mac, switch it on in Settings, Sources, in the panel's "Set up" tab, or in the set-up window. Annular starts Codex's own local server for each reading, asks it for your limits, and hangs up. Codex keeps its login and talks to OpenAI itself. Annular never sees that login, and only ever reads. With Claude and Codex both on, the menu bar shows one ring for each, the panel has a tab for each, and the rings in the corner show small tags, CL and CX, to switch between them. Codex alone is enough: Annular then works without Claude Code.

Versions before 1.1 had their own "Sign in with Claude". If you used it, version 1.1 deletes that old login from your Keychain and shows you once what changed. Your history, settings, and themes stay.

To disconnect, switch a source off in Settings, Sources. Claude Code's own login is never touched, and switching the feed off puts your earlier status line setting back.

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

Click the widget to open its panel, and click again to close it. From version 1.2 on, hovering opens the panel only when you switch on Also open the panel on hover 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. With the status line feed on, each row also says where its number came from and how old it is. When only the feed has numbers, the row and the ring for a single model are empty, or left out if you use the feed alone.

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. From version 1.2.1 on, a double-click on a theme file adds the theme and switches to it. The built-in themes, the theme format, and themes made by others are in a public repo: github.com/tearless-ai/annular-themes.

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.
  • SET UP: nothing is connected yet. The set-up window opens by itself at launch, and you find it again as Set Up Claude in the right-click menu, or with a click on the corner widget.
  • STALE: the last refresh failed, or the Claude Code login ran out, so the rings dim and show the last numbers Annular has. Annular tries again by itself. When the login ran out, open Claude Code, which renews it.

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

  • EXPIRED: the Claude Code login ran out. Open Claude Code, which renews it.
  • WAITING: the status line feed is on and is your only source, and Claude Code has not replied 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 the Claude Code login in the Keychain could not be read.

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

  • No login of its own: Annular reads Claude Code's Keychain item and holds the token in memory only. Versions before 1.1 kept one item named Annular (service app.annular.oauth), which version 1.1 deletes.
  • The status line feed, when it is on: a small script, the feed file, and your earlier status line command in ~/Library/Application Support/Annular/, and, when Claude Code had a settings file, a copy of it at ~/.claude/settings.json.before-annular.
  • 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

  • If the status line feed is on, switch it off in Settings, Sources, first. That points Claude Code's settings at your own status line again; deleting Annular's folder while the feed is on would leave Claude Code without a status line.
  • 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.