GitHub - joshwallerr/claudeviewer: A native macOS menu bar app that shows the live status of every running Claude Code session on your machine, plus your claude.ai usage limit, at a glance. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
joshwallerr
claudeviewer
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>4 Commits<br>4 Commits
Sources/ClaudeViewer
Sources/ClaudeViewer
scripts
scripts
.gitignore
.gitignore
LICENSE
LICENSE
Package.swift
Package.swift
README.md
README.md
View all files
Repository files navigation
Claude Viewer
A native macOS menu bar app that shows the live status of every running Claude Code session on your machine, plus your claude.ai usage limit, at a glance.
⚪⚪🟠 (left: inactive, middle: waiting for you, right: working)
Pulsing orange dot — Claude is thinking or running a tool
Solid white dot — session is idle, waiting for your input
Dimmed white dot — session has been idle for more than 2 hours
Click the dots to open a popover listing each session by its AI-generated title, its repo, status, and current context window usage, plus an orange progress bar for your 5-hour claude.ai limit with the time until reset.
Features
Watches ~/.claude/sessions/ in real time via filesystem events — no polling overhead
Reads each session's JSONL transcript to extract context usage and the title Claude auto-generated for it
Hides sessions that have never been interacted with (just opened, or freshly /cleared)
Sorts: working first, then waiting-on-you, then stale, with the most recently active at the top
Polls claude.ai/api/organizations//usage every 5 minutes (and on popover open) for your 5-hour limit
"Launch at login" via SMAppService
Install
Requires macOS 13+ and the Swift toolchain (xcode-select --install).
cd claude-viewer<br>./scripts/build-app.sh<br>open ~/Applications/ClaudeViewer.app">git clone this repo><br>cd claude-viewer<br>./scripts/build-app.sh<br>open ~/Applications/ClaudeViewer.app
The script builds and installs the .app bundle to ~/Applications/ atomically (no stray copies).
Setup: usage limits
Open the popover → click the gear icon → pick the browser you're already signed in to claude.ai with. The app pulls the sessionKey cookie out of the browser's local cookie store (Chromium-based browsers only — Brave, Chrome, Arc, Edge) and stores it at ~/Library/Application Support/ClaudeViewer/session-key (mode 0600).
macOS will ask for keychain access once to read your browser's encryption key. Click "Always Allow".
If you don't use a Chromium browser, the settings sheet's "Other sign-in methods" disclosure offers:
An embedded WebView sign-in (note: Google SSO often blocks embedded browsers; use email login inside it)
Manual paste of the sessionKey from DevTools
How it works
Surface<br>Source
Dots in menu bar<br>~/.claude/sessions/.json heartbeat files — one per running claude process. status field is busy/idle/shell, mapped to working/idle.
Session title<br>Latest ai-title (or custom-title/agent-name) entry in ~/.claude/projects//.jsonl
Context %<br>Sum of input_tokens + cache_creation + cache_read from the latest assistant message in that JSONL. The denominator (200K vs 1M) is auto-detected by checking whether any session has ever exceeded 200K.
5-hour limit<br>GET https://claude.ai/api/organizations//usage with the sessionKey cookie
Brave/Chrome cookie<br>AES-128-CBC, key derived via PBKDF2-HMAC-SHA1 (salt saltysalt, 1003 iters, 16-byte key, 16-space IV) — Chromium's standard recipe
Caveats
claude.ai/api/... is not a public Anthropic API. They could change or rate-limit it. The app degrades gracefully — limits row shows an error, everything else keeps working.
Cookie expiry: claude.ai sets a long-lived sessionKey, but log-outs / password changes / cookie clears will invalidate it. Re-import from the browser when that happens.
Local-only: the app never sends anything to a server I control. The only network call is to claude.ai with your own cookie.
About
A native...