Blog
Harjas Singh
The first prototype of the usage feature had a login button.
You'd click Connect. Claude Pulse would open Safari. You'd sign in with your Anthropic account. A redirect URL would bounce back into the app. We'd store a refresh token. Standard OAuth, the way every SaaS product onboards.
I used it once and tore it out.
The problem wasn't the OAuth flow. OAuth worked fine. The problem was philosophical: I was asking the user to authenticate with the same Anthropic account they'd already authenticated with, on the same machine, to the Claude Code CLI, roughly ten minutes earlier.
A Claude Pulse user, by definition, already has the Claude CLI installed and signed in. That's the whole premise of the product. We sit next to the CLI and surface its state in the notch.
So why was I asking them to sign in again?
The answer is: because it was easier for me. Building a parallel OAuth flow is a known pattern. Reading another app's credentials is not. I picked the path that felt safer for the developer, not the user.
Here's what actually happens when you run claude for the first time. The CLI walks you through an OAuth flow. When it succeeds, it stores a refresh token and an access token in the macOS Keychain, under its own bundle identifier. Every subsequent claude run reads those tokens, refreshes them if needed, and talks to Anthropic's API.
The tokens are right there. In the Keychain. On the same machine. Under the user's account.
Claude Pulse just needs to read them.
The implementation lives in PlanUsageService under ClaudePulse/Services/Usage/. When you click Connect in the Claude Pulse menu, we do exactly one thing: we ask the macOS Keychain for the Claude CLI's credentials.
macOS responds with a dialog. The same dialog you've seen a hundred times before:
"Claude Pulse wants to access key '…' in your keychain."
[Deny] [Allow] [Always Allow]
You click Always Allow. macOS remembers your choice at the system level. Claude Pulse reads the token, hits Anthropic's usage endpoint, and the 5-hour and weekly bars light up.
You never see that prompt again. Not on the next launch, not next week, not ever. Silent forever. Because it's your machine, your Keychain, and you told it this was fine.
Three numbers, live:
The per-session context bars are especially useful when you're running several Claude Code sessions in parallel. You're not estimating context based on message count or some heuristic. The CLI writes the real usage block to its JSONL after every model turn. Claude Pulse reads that block. The number you see is the number Anthropic sees.
Per-model context limits are in ClaudePulse/Services/Session/ModelLimits.swift. Opus 4.7 and Sonnet 4.6 are 1M tokens. Sonnet 4.5 and Haiku 4.5 are 200k. We render the fill against the right denominator for each session automatically.
The CLI refreshes its own tokens opportunistically — every time you run a command, it checks if the access token is close to expiring and rotates it if so. Claude Pulse just re-reads the Keychain on every poll. When the CLI has a fresh token, we have a fresh token. When the CLI's token expires before the next poll, we get a 401 from Anthropic's usage endpoint.
We handle that by keeping the last successful reading on screen and retrying on the next poll. The bars don't jump to zero or flash red. They just freeze for ~60 seconds, the CLI does its thing in the background, and our next poll succeeds. No user action required. If the CLI has fully logged out — which almost never happens in practice — the bars eventually stop updating and the Connect button reappears.
This is the benefit of being a read-only consumer of someone else's credentials. We don't have to think about refresh logic, retry windows, or token rotation edge cases. The CLI already solved all of that. We just sit on top.
There's a Disconnect option in the Claude Pulse menu. It does one thing: it hides the usage bars locally. It does not revoke your token at Anthropic. If we revoked the token, the CLI would lose its login and you'd have to re-authenticate the CLI too. That's not a good tradeoff for hiding a UI element.
Disconnect is a view-layer toggle. Your CLI keeps working. Claude Code keeps working. You just don't see the bars anymore. If you change your mind and click Connect again, the bars come back instantly with no prompt — because macOS remembered your "Always Allow."
This is a small technical choice with a large behavioral consequence: Claude Pulse is the only macOS surface on your machine that shows your Claude usage ambiently, and it took zero incremental setup to get there.
Every other usage tool I've seen — command-line, web dashboard, whatever — requires an active check. You have to go look. That means you only look when you're worried, which is often when you've already run out.
The notch flips that. You see the numbers every time you look at your screen, whether you were asking for them or not. You notice your 5-hour bar is at 78% at 2pm and decide to slow down. You notice your context is at 80% and decide to compact. You notice your week is at 90% on a Wednesday and take Friday off from Claude.
That's the feature. The Keychain-read-only, no-second-OAuth implementation is just what made it possible to ship without asking the user to think about authentication twice.
Nothing. This is the shape.
If the CLI ever changes how it stores credentials — different keychain entry, different bundle ID, different format — we'll have to update. That's a real maintenance cost. But so far it's been stable across several CLI releases, and if the maintenance cost ever stops being worth it, the worst case is we add a second OAuth flow as a fallback. We don't lose the feature. We just lose the "no second login" story.
For now, the story is intact. One click. One macOS prompt. Silent forever.
If you're running Claude Code and not seeing your usage, you're flying blind between rate limits. Claude Pulse fixes that without asking you to authenticate anything twice. Download and check the menu — Connect is one click away.
More from the workshop
Running Claude Code in tmux means juggling approvals across panes you can't see. Here's why standard notification approaches break down — and how Claude Pulse routes approvals to the right pane by PID.
Running 3-6 Claude Code sessions? Here's how the context-switching tax kills your flow and what you can do about it.
Every missed approval costs ~10 minutes. With multiple sessions, that's hours per day. Here's the math and how safety-aware batch approval fixes it.