Usage
Menu bar & widgets
Keep an eye on working agents, plan limits and local servers from the menu bar and three desktop widgets, without opening a window.
Codz lives in the menu bar as well as its window. The menu bar item says how many agents are working, or how full a plan is when one needs your attention, and its popover shows today’s usage, how full your plans are and where they’re heading, who is working, and which local servers are running. Three desktop widgets carry the same readings onto your desktop.
The menu bar item
The item is a bolt, filled while any agent is working, with the number of working agents beside it. It shows a cup instead while Codz is keeping the Mac awake and nothing is working. Click it to open the popover.
While a plan window is three quarters used or will run out before it resets, the bolt becomes two rings: the outer one is your fullest short window (such as Claude’s 5-hour), the inner one your fullest weekly window, and the figure beside them is the window that needs you first, such as 62%. A green dot on the rings means agents are still working. When a window has run out, its ring closes and the figure says when it’s back, such as 9:25 (or Tue if that’s another day); ≥92% means the last reading is a little old, so the window is at least that full. Hover the item for the window’s name and what’s next.
- Turn the rings off with Settings ▸ General ▸ Plan limits in the menu bar. It is on by default.
- Hide the number with Settings ▸ General ▸ Menu bar count. It is on by default.
- Turn off Settings ▸ General ▸ Show in Dock to keep Codz out of the Dock and the app switcher. The menu bar item stays.
The popover
From the top:
- The header says when the readings were last updated. The arrow refreshes them.
- Today: the tokens so far and what they’re worth at list price, such as “23.4M tokens today · $85.40 est.”, with a bar for each hour. A charge a provider reported to you is shown apart as “reported”, and
≥means a model has no list price yet. It follows the day picked in the dashboard, so it can read “tokens yesterday”. - Limits: the window that needs you first as a small chart of how it filled and where it’s heading, then every other Claude, Codex and Cursor window as a bar with where it lands or when it resets, and Claude’s Extra usage when it’s on. With more than five windows, the rest fold into one line you can open. When another provider has room, Continue in Codex (or the provider with room) moves the chat. See Plan limits.
- Working now: up to four working agents, each with its title, folder, model, how long it has been running and how full its context is. Click one, or View all, to open Agents.
- Local servers: up to three development servers. Click one to open it in your browser. Free :3001 copies
PORT=3001, the next free port, and Manage opens Ports. See Local ports. - This Mac: Keep awake, and Performance, which says when memory is under pressure and otherwise how much your idle agents hold that you could reclaim. Click it to open the Performance page there.
- Open Codz brings up the main window, and the power button quits Codz.
If Codz hits an error collecting, the popover says so above Open Codz.
Keep awake
Keep awake stops your Mac from going to sleep: on its own while an agent is working, or for as long as you ask. Its line in the popover says what it is doing, such as Inactive or Awake · local task.
- Start keeps the Mac awake for 30 minutes, 1 hour, 2 hours or Indefinitely. Stop ends it early. A manual session also ends when Codz quits or the Mac sleeps.
- Settings ▸ General ▸ Prevent sleep while running keeps the Mac awake on its own while a local agent turn is active. It is on by default.
- With Codz Remote, Keep this Mac awake in Settings ▸ Connections keeps it awake while it is plugged in and remote access is on.
- Low-battery cutoff, in Settings ▸ General ▸ Keep awake, releases keep-awake at a battery level from 10% to 50%, 20% to start. Automatic keep-awake resumes on power; a manual session has to be started again.
Keep awake prevents idle sleep only, so keep the lid open. To keep local tasks and manual sessions running with the lid shut, turn on Keep running when the lid closes in Settings ▸ General ▸ Keep awake and set up the Codz helper it needs with Set up…. While it is active, system sleep is disabled, so turn it off before you choose Sleep. Before deleting Codz, click Remove beside Remove closed-lid helper to restore your previous sleep setting.
Codz also stops keeping the Mac awake when macOS reports thermal pressure or a critical battery, and says why in the popover.
Desktop widgets
Codz installs three widgets. To add one:
- Right-click the desktop, or open Notification Center, and choose Edit Widgets.
- Find Codz in the list.
- Drag the widget, in the size you want, onto your desktop or into Notification Center.
| Widget | Sizes | Shows | Plan |
|---|---|---|---|
| Tokens Today | Small, medium, large | Today’s tokens and what they’re worth, with your recent days | Free (your last 7 days) |
| Plan Limits | Small, medium, large | Every plan window: Claude, Codex, Cursor and the others | Free |
| Active Agents | Small, medium | The agents working right now | Free |
Clicking a widget opens the page behind it: Usage for Tokens Today and Plan Limits, and Agents for Active Agents.
Tokens Today
Today’s tokens in large type, “so far”, with their API value beside them, such as “$85.40 est.”, and a provider’s charge apart as “reported”. Bars show your recent days, today’s drawn lighter because it isn’t over, and nothing compares today with another day. The medium size adds your top three providers and a month of bars with their peak; the large size adds this week and the month so far, and names the peak’s day. Cursor’s row shows its context fill when Cursor’s account usage isn’t available, never a made-up total. See Usage analytics for where the numbers come from.
Without Pro, the bars cover your last 7 days.
Plan Limits
- Small: two rings, your fullest short window outside and your fullest weekly window inside, with the percentage in the middle and a line saying what’s next, such as “Out 9:00 AM”.
- Medium: up to three windows, each with its bar and a line such as “Runs out 9:00 AM · Resets 9:25 AM” or “Lands near 90% · Resets Tue 9:00 AM”, then how many more there are.
- Large: the window that needs you first as a small chart of how it filled and where it’s heading (or, once it has run out, when it’s back), then four more windows and how many more there are.
A bar fills grey while there’s room, amber from 75% or when it will run out before it resets, and red from 90% or when it’s out. The hatched part past the fill is where it’s heading at the current pace, and the small tick is how far through the window you are. ≥ means the reading is old enough that the window is at least that full, and — means it has reset and Codz is waiting for a new reading.
Until Codz has a reading, it says “Open Claude Desktop or send a Codex request to read your limits.”
Active Agents
How many agents are working, and up to three by name with how long each has been running; the medium size adds each one’s project. A line at the foot names the projects, how many more are working, and Keep awake on while Codz is keeping the Mac awake. When nothing is running it says “No agents working right now.”
How widgets stay current
Widgets don’t read your agents’ files themselves. Codz writes a small snapshot for them as it collects, so they update while Codz is running.
- When the snapshot is more than 15 minutes old, a widget adds “as of” and the time it was taken. Active Agents says “Codz isn't collecting right now.” instead of claiming nothing is running. Plan windows age on their own: a reading older than its window allows reads as ≥, and a window that has reset since reads —.
- While the dashboard is on another day, Codz stops updating the widgets until you come back to today, so a past day is never labelled Today.
- A widget that says “Open Codz to …” has no snapshot yet. Open Codz once.
Questions
The popover shows zeros, but my agents have been busy. macOS may be blocking Codz from reading the providers’ files. Turn Codz on in System Settings ▸ Privacy & Security ▸ Full Disk Access.
A widget shows an old time. Codz isn’t running, or the dashboard is on another day. Open Codz and go back to today.
The menu bar item is missing. The item is there only while Codz is running. Open Codz from your Applications folder.