Omarchy's Agent Usage Panel: Tracking Claude Code Limits and Token Spend
Omarchy puts your coding agent's plan usage in the top bar — limits consumed, prepaid balance, and tokens by day and model. Here's what it shows and how to refresh it.
What does the Omarchy usage panel show?
Omarchy puts an icon in the top bar that reports how much of your coding agent’s allowance you have consumed. Clicking it shows four things:
- Your plan type — which subscription or billing arrangement the agent is running under.
- The percentage consumed of your session and weekly limits, for plans that work that way.
- The remaining prepaid balance, for plans that work that way instead.
- Token usage broken down by day and by model.
The data refreshes every 15 minutes. You can force an update at any time:
omarchy agent usage-updateThe panel reports on your default agent — the one set with omarchy default agent <name> — so if you run several agents, the bar is showing you one of them, not a combined total. See how to set your default agent if you have not chosen one yet, or Omarchy for background on the distribution.
TL;DR
- The usage indicator lives in the Omarchy top bar and reports on your default agent.
- It shows plan type, limit consumption or prepaid balance, and per-day, per-model token counts.
- Data regenerates every 15 minutes;
omarchy agent usage-updateforces a refresh immediately. - Which fields you see depends on your plan. Subscription plans with rolling windows show percentages; prepaid arrangements show a remaining balance.
- It reports one agent, not all of them. Change which one with
omarchy default agent <name>. - The per-model breakdown is the useful part — it shows where spend actually goes, which a single percentage does not.
Everyone else built a construction worker.
We built the contractor.
One file at a time.
UI, API, database, deploy.
Why does a desktop need a token meter?
Because the cost of running a coding agent is invisible at the moment you incur it, and visible only later.
A conventional workflow gives you two options. You can check a web dashboard, which means leaving the terminal, logging in, and interpreting a page designed for billing rather than for pacing. Or you can not check, which is what most people do, and find out where you stand when something stops working mid-task.
Neither is good when the resource is consumed by a background process you started and then stopped watching. An agent working through a long refactor can burn a meaningful share of an allowance while you are reading something else. A bar indicator changes that from a thing you remember to check into a thing you glance at.
This is the same reasoning behind putting battery and network in a status bar. The information is not complicated. It just needs to be where your eyes already are.
What the per-model breakdown tells you
The headline percentage answers “how much is left.” The per-model, per-day breakdown answers the more useful question: where did it go.
Two habits show up clearly once you can see this:
Model choice dominates. Running a large model for tasks a smaller one handles fine is the most common source of avoidable spend, and it is invisible until something separates usage by model. If one model accounts for most of your consumption on days when your work was routine, that is a specific, actionable finding rather than a vague sense that you are using too much.
Spend is bursty, not steady. Daily figures usually show a few heavy days rather than an even spread. Knowing which days were heavy — and remembering what you were doing on them — tells you which kinds of task are expensive. That is far more useful for pacing than a single running total, because it lets you decide when to reach for the agent and when to do something by hand.
How does the refresh cycle work?
The panel regenerates its data every 15 minutes on its own. That cadence is a deliberate compromise: usage figures come from a provider API, and polling continuously would mean a constant stream of requests to answer a question that changes slowly.
The consequence is that the number in your bar can be up to 15 minutes stale. Most of the time this does not matter. It matters in exactly one situation — when you are close to a limit and deciding whether to start something expensive. In that case, run omarchy agent usage-update first and read the fresh number rather than trusting the cached one.
It is also worth knowing that the panel reflects what the provider reports. If a provider’s own accounting lags, the panel inherits that lag; a manual refresh updates Omarchy’s copy of the data, not the provider’s calculation of it.
Which agents does this work with?
The panel is tied to whichever agent is currently your default. Omarchy pre-wires ten agent CLIs — claude, codex, opencode, agy, copilot, crush, grok, pi, omp, and ori — and the usage integration reads from the one you have selected.
The practical implication for anyone running more than one agent is that switching your default also switches what the bar is measuring. If you use Claude Code for large work and a cheaper agent for small edits, the bar shows one of those stories at a time. There is no combined view, and for cost purposes that is worth remembering before you conclude that your total consumption is lower than it is.
Knowing what agent work costs
The reason a per-model breakdown beats a single percentage is that it turns an anxiety into a number. Once you can see what a particular kind of task actually cost, you can decide whether it was worth it.
That judgement gets more interesting the bigger the thing you are building. A product agent like Remy builds a full-stack app you own — repository, database, auth and all — for roughly $100–$500 in AI tokens at provider rates, once, on top of a flat platform rate. Whether that is expensive depends entirely on what it replaces: a one-time build you keep, against a per-seat licence that renews for as long as the team exists.
Frequently Asked Questions
How do I refresh the Omarchy usage panel?
Run omarchy agent usage-update. The panel also regenerates automatically every 15 minutes, so a manual refresh is only needed when you want a current figure immediately.
Does the usage panel show all my agents at once?
No. It reports on your default agent only. Change which agent it tracks with omarchy default agent <name>, or through Setup › Defaults › Agent in the Omarchy Menu.
Why does the panel show a percentage for one plan and a balance for another?
Because plans are structured differently. Subscription plans that allocate usage over rolling windows are reported as a percentage consumed; prepaid arrangements are reported as a remaining balance. The panel displays whichever measure applies to your account.
Is the number in the bar live?
Not exactly. It is regenerated on a 15-minute cycle, so it can be slightly behind. Run omarchy agent usage-update before making a decision that depends on the exact current figure.
Can I see which model is costing me the most?
Yes. The panel breaks usage down by day and by model, which is the view that shows where consumption is actually concentrated. A single overall percentage cannot tell you that.
Do I need the usage panel to use coding agents on Omarchy?
No. It is a convenience, not a requirement. The agent CLIs work whether or not you look at the indicator, and agents that do not report usage data simply will not populate it.
