claude-status-bar: a macOS menu bar indicator for Claude Code sessions

The gap claude-status-bar fills between Claude Code and the menu bar

Claude Code runs in a terminal or in the Desktop app's Code tab. When a turn takes a minute or two, the terminal window is usually behind a browser, and the only way to know whether the agent is still working or has stopped to ask for permission is to switch back and look. This project puts that state in the macOS menu bar instead: an animated icon while Claude is thinking or running a tool, a yellow dot when a permission prompt is waiting, and the elapsed time of the current turn.

The intended user is someone who already runs Claude Code on a Mac and tabs away during long stretches. The README describes the motivation directly: it was built so you can tab away during a long thinking stretch and still see, at a glance, whether Claude is working, waiting on you, or done. It is not a dashboard, does not track token usage or cost, and has no window or dock icon. If you want per-session analytics, this is the wrong tool.

How the hook polling and session aggregation actually work

The app is stateless. Claude Code fires hooks as it works, and the app polls those updates, then aggregates them across every live session into one icon. The aggregation rule is priority-based: if any session is awaiting permission, that state wins over a session that is merely thinking, so a permission prompt is never hidden behind background work. The dropdown lists every live session separately.

Integration happens through ~/.claude/settings.json. The installer merges its hook entries into that file and backs it up first. That is the whole coupling between the two programs, which also explains the lifecycle: you do not open the app, it opens itself when a Claude Code session starts and quits when none is running. Launched by hand with no session active, it quits again after a few seconds. The README states the only manual launch is the first one after install, to set up the hooks.

Coverage is uneven and the README is explicit about it. The Claude Code CLI, the Desktop app's Code tab, and the Cursor Claude Code extension are tracked. The Claude Desktop Chat/Cowork tab is not. The README also notes that precise per-tab focus is still in progress and points to issue #19, so the multi-session dropdown is the current answer rather than per-tab attribution.

Installing claude-status-bar with Homebrew and checking the first session

Homebrew is the recommended path. The cask install and the immediate launch are one line, and the launch is what wires up the Claude Code hooks:

brew install --cask claude-status-bar && open -a "Claude Status Bar"

After that the app starts itself whenever Claude Code runs. If you already installed from the DMG, the same command switches you to Homebrew; the README says settings and hooks carry over and the old copy cleans itself up on first launch. The DMG route is the alternative: download ClaudeStatusBar.dmg from Releases, drag the app into Applications, launch it once, then start a new Claude Code session.

The important caveat is timing. If you install or update mid-session, sessions that are already open appear the next time they do something, either a prompt or a tool call. Starting a new claude session also works. So the first thing to verify after install is not the icon but a fresh session:

claude

The icon should appear while Claude Code is running. If it does not, check that the hooks landed in ~/.claude/settings.json, since that file is where the installer merges them. The README points to TROUBLESHOOTING.md for the rest. Requirements are macOS 12 or later, Claude Code (CLI or Desktop app), and Node.js.

Animation styles, color modes, and what the menu lets you change

The menu carries the configuration. Show timer toggles the elapsed clock. Thinking words rotates a playful verb in place of Thinking, on by default, mirroring Claude Code's own habit. Animation style has three options: Claude Spark, the web and chat morph spark; Claude Code, the terminal glyph spinner; and Clawd Crab Walking, a pixel-art Clawd crab that scuttles while Claude works. Icon color is Orange or System, and all three styles follow it. In System mode, Crab Walking renders as a shaded monochrome silhouette that matches the menu bar.

This is a cosmetic layer, and it is worth being honest about what that means. The state machine underneath is small: thinking, running a tool, awaiting permission, idle. The tool label is short and generic (Editing, Reading, Running command, Using tool), so you learn the category of work, not the file or command. The three animation styles exist because the icon is the only surface, and the README treats that as the point rather than a limitation. The menu also shows the current version and update state.

Where claude-status-bar breaks down or is the wrong choice

The hard boundary is the operating system. This is a macOS menu bar app, so Windows and Linux users have nothing to install here, even though people search for a Claude Code status line on Windows. That search usually points at a different mechanism: a status line rendered inside the terminal by Claude Code itself, configured through settings, not an icon in the system menu bar. If that is what you want, this project is not it.

The second boundary is the Chat/Cowork tab in Claude Desktop, which the README marks as not tracked. If most of your Claude usage happens there rather than in the CLI or the Code tab, the icon will sit idle and tell you nothing useful.

The third is the mid-session behaviour. Installing or updating while sessions are open means those sessions are invisible until they next act. That is a real gap in the first-run experience, and the README calls it out rather than hiding it. There is also no documented rollback path beyond the uninstall steps: the README describes removing hooks with the bundled uninstall script and removing the app and its files with brew uninstall --zap, but it does not document reverting the settings.json merge by hand. If you keep a heavily customized ~/.claude/settings.json, read the installer behaviour before running it.

How it differs from a Claude Code status line inside the terminal

The obvious alternative is Claude Code's own status line, which renders text at the bottom of the terminal session. The difference in approach is where the state lives. A status line is inside the process you are already looking at, so it disappears when you switch windows, and it belongs to one session at a time. claude-status-bar moves the same class of information out of the terminal and into the macOS menu bar, which is shared across applications and visible regardless of which window has focus.

That trade is not free. A terminal status line can be scripted and customized to show whatever you can compute, and it works on any platform Claude Code runs on. The menu bar app gives up that portability and that flexibility to gain always-visible state and cross-session aggregation, including the priority rule that surfaces a pending permission prompt over background work. It also gives up terminal real estate, which some users care about, in favour of a single icon.

If your complaint is that the terminal is too cramped or that you want to see status while reading documentation in a browser, the menu bar approach addresses it. If your complaint is that the status line is not informative enough, this project does not add depth; it relocates a small amount of state.

Maintenance, updates, and the MIT licence boundary

The last push to the repository was on 2026-08-09, and the most recent release listed is v0.4.4 from 2026-08-06. Releases v0.4.3 and v0.4.2 landed in late July 2026, so the cadence over that window is a few weeks apart. The repository is not archived.

Updating is handled in the menu. Installed via brew, it shows Update via brew with a copy button, and the README notes it appears only once Homebrew can actually deliver the new version, which can lag a release by up to a day. Installed via DMG, Update available opens the releases page and offers a one-click Switch to Homebrew. The manual equivalent is:

brew upgrade --cask claude-status-bar

Hooks refresh themselves on the next launch, so there is nothing to run by hand. One upgrade detail the README singles out: coming from 0.3.x via DMG, launch the app once after dragging it into Applications, because that is what retires the old-named copy.

The licence is MIT, which covers the source code. The README is explicit that this conveys no rights to Anthropic's trademarks or brand, and that the project is unofficial and not affiliated with, endorsed by, or sponsored by Anthropic. Claude and the Claude spark logo are used nominatively. If you plan to redistribute a build or use the icon in a product, that trademark note is the part to read, not the MIT text. The README also states the app's only network activity is a once-a-day update check against GitHub's and Homebrew's public APIs, with details in PRIVACY.md.

Editorial conclusion

Adopt it if you run Claude Code on macOS 12 or later, keep long sessions in the background, and want the permission prompt to be visible without watching the terminal. Skip it on Windows or Linux, where the menu bar does not exist, and skip it if you want a status line rendered inside the terminal itself rather than an icon in the system menu bar. Before installing, open ~/.claude/settings.json and confirm you are comfortable with an installer merging hook entries into it, since that file is the integration point and the README says a backup is taken first. The README does not document rollback beyond the uninstall script and brew uninstall --zap.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. m1ckc3s/claude-status-bar on GitHub
4. README
5. Releases