If you've got multiple Claude Code sessions running across different projects and you're constantly losing track of which agent is doing what, developer joshwallerr just shipped a tool worth bookmarking. Claude Viewer is a native macOS menu bar app that surfaces the live status of every active Claude Code instance on your machine, along with your claude.ai usage limit — all without leaving the menu bar. The app uses color-coded dots to communicate session state at a glance: a pulsing orange dot means Claude is actively thinking or running a tool, a solid white dot signals an idle session waiting for input, and a dimmed white dot appears after two hours of inactivity. Clicking any of those dots opens a popover that lists every session by its AI-generated title, the associated repo, current status, and context window usage as a percentage. Under the hood, Claude Viewer takes a filesystem-events approach rather than polling. It watches ~/.claude/sessions/ in real time to detect running instances via heartbeat JSON files — one per active claude process. Session titles are pulled from each session's JSONL transcript by reading the latest ai-title (or custom-title/agent-name) entry, and context window percentage is calculated from input_tokens plus cache_creation and cache_read on the most recent assistant message. The denominator auto-detects between 200K and 1M depending on whether any session has ever exceeded 200K tokens. On the usage limit front, the app polls claude.ai/api/organizations/
Setup and Browser Integration
Getting usage limits working requires importing your claude.ai sessionKey cookie from a Chromium-based browser: Brave, Chrome, Arc, and Edge are all supported. The app extracts the cookie using Chromium's standard AES-128-CBC recipe — PBKDF2-HMAC-SHA1 with saltysalt as the salt, 1003 iterations, a 16-byte key, and a 16-space IV — then stores it at ~/Library/Application Support/ClaudeViewer/session-key with mode 0600 permissions. macOS will prompt once for Keychain access to read the browser's encryption key; joshwallerr asks users to click "Always Allow" to avoid repeated prompts. For developers who don't use a Chromium browser, two alternatives exist: an embedded WebView sign-in (with a caveat that Google SSO often blocks embedded browsers — email login is recommended instead) or manually pasting the sessionKey from DevTools. The cookie is long-lived by default, but logouts, password changes, or cleared cookies will invalidate it and require re-importing.
Installation and Requirements
Claude Viewer requires macOS 13 or later and the Swift toolchain (installable via xcode-select --install). After cloning the repo and running ./scripts/build-app.sh, the app bundle installs atomically to ~/Applications — no stray copies cluttering up your system. "Launch at login" is handled through SMAppService, Apple's modern launch-on-login mechanism. The developer emphasizes that everything stays local: no data leaves your machine except a direct call to claude.ai with your own sessionKey cookie. There's no telemetry, no backend server, nothing leaving your network.
Key Takeaways
- Real-time filesystem watching of ~/.claude/sessions/ means zero polling overhead and instant status updates
- Context window percentage auto-detects between 200K standard and 1M extended context tiers
- Usage limit tracking depends on an undocumented claude.ai API that could change without warning
- Cookie extraction only works with Chromium-based browsers; Firefox and Safari users fall back to WebView or manual paste
The Bottom Line
This is the kind of tool that feels inevitable once you see it — if you're running multiple Claude Code agents, having them visible in the menu bar instead of hunting through terminal tabs is a genuine quality-of-life improvement. Just don't sleep on those usage limits; this app makes it way too easy to burn through your five-hour window without realizing it.