Claude Code Lightbar for Mac OS

Claude Code Lightbar for Mac OS, a full-width red bar that displays Claude Code session status across all screens, is now available in version 1.0 exclusively for macOS. The bar shows a solid red when a session is busy, pulses when user input is needed, and disappears when a turn finishes, driven by Claude Code hooks via a local Swift app and LaunchAgent.

Version 1.0 · macOS only uses AppKit + launchd ; there is no Windows or Linux build . A full-width red bar along one edge of every screen that tells you, from across the room, what Claude Code is doing. It sits on the top edge by default position, thickness, and color are all changeable — see Configuration configuration . Solid red bar — at least one session is busy Claude working . Pulsing red bar — a session needs a response from you now a permission prompt, or Claude blocked waiting for input . No bar — a turn simply finished, or nothing running. Busy wins: if any session is still working the bar is solid; it pulses only when one has an active prompt for you a permission request or an explicit question . A turn that just finishes clears the bar. The bar is click-through it never intercepts your mouse and floats above everything, including fullscreen apps, on every Space and every monitor. Note: pulsing is driven by Claude Code's Notification hook, which fires for a real prompt a permission request, etc. . The ~60sidlenotification is deliberately ignored hook.sh filters the "waiting for your input" message , so the bar never blinks just because a finished session is sitting there. One consequence: Claude Code has no distinct event for "ended a turn with a question," so a plain conversational question at the end of a turn reads as done no bar — only actual prompts pulse. Structured AskUserQuestion promptsdopulse, via a PreToolUse / PostToolUse hook on that tool. Left: solid red along the bottom edge = Claude is working; it pulses when Claude needs a response from you. Right: the menu-bar menu for live configuration. macOS uses AppKit + launchd . Xcode Command Line Tools — provides swiftc to build. Install with: xcode-select --install Claude Code CLI — this is driven by Claude Code https://docs.anthropic.com/en/docs/claude-code hooks. It works with any locally-running Claude Code terminal or IDE extension . It does not work with cloud sessions claude.ai/code — those run remotely and can't reach your local machine. No other dependencies: no Homebrew, no jq , no runtime. Just the system Swift compiler and plutil built into macOS . git clone https://github.com/gregsramblings/claude-status-bar.git cd claude-status-bar ./install.sh install.sh builds the app, installs a run-at-login LaunchAgent paths derived from wherever you cloned — nothing hardcoded , starts it, then prints a hooks block . Copy that block into ~/.claude/settings.json merge it into the top-level JSON object; if you already have a "hooks" key, add the four events to it . The block looks like this, with real paths filled in: "hooks": { "UserPromptSubmit": { "hooks": { "type": "command", "command": "bash /path/to/claude-status-bar/hook.sh busy" } } , "Stop": { "hooks": { "type": "command", "command": "bash /path/to/claude-status-bar/hook.sh waiting" } } , "Notification": { "hooks": { "type": "command", "command": "bash /path/to/claude-status-bar/hook.sh needs input" } } , "SessionEnd": { "hooks": { "type": "command", "command": "bash /path/to/claude-status-bar/hook.sh end" } } } Then start a new Claude Code session and give it something to do — the red bar appears while it works. Hooks load at session start, so already-open sessions won't drive the bar until restarted. echo '{"session id":"test"}' | ./hook.sh busy bar should appear echo '{"session id":"test"}' | ./hook.sh end bar should disappear ./uninstall.sh Stops and removes the LaunchAgent and the state directory. It intentionally does not edit settings.json — remove the four ccbar hooks entries yourself, then delete the repo folder. - Claude Code hooks fire on state change and run hook.sh , which writes one small JSON file per session into ~/.claude/ccbar/state/<session id .json : UserPromptSubmit → busy you handed off; Claude is working Stop → waiting turn finished Notification → notify , which hook.sh splits into needs input a real prompt → pulse or waiting the idle timeout → no bar PreToolUse matching AskUserQuestion → needs input pulse while a multiple-choice question waits on you ; PostToolUse → busy solid again once you answer SessionEnd → deletes the file ccbar a tiny AppKit app, one borderless click-through window per screen at .screenSaver level, on all Spaces polls the state directory every 0.4s: solid if any live session is busy , else pulsing if any is needs input , else hidden waiting — a finished turn — shows nothing . Multi-session just works: each session is its own file keyed by session id , so three concurrent sessions share one bar — solid if any is working, pulsing if any needs your input. Stale files older than 12h, e.g. from a crash that skipped SessionEnd are ignored. ccbar adds a small bar-shaped icon to the macOS menu bar . Click it to configure the bar live — no rebuild, no restart: | Menu item | Default | Meaning | |---|---|---| Position | Top | Pin the bar to the Top or Bottom edge. | Thickness | 6 px | Bar thickness presets 4 – 30 . Bump for a big room. | Bar Color… | red | Opens the macOS color picker; recolors the bar live. | About ccbar | — | Description, author, link to this repo. | Quit ccbar | — | Stops the app unloads the LaunchAgent so it stays down . | Choices persist in UserDefaults across restarts. The remaining tunables are still compile-time constants at the top of ccbar.swift rebuild + restart after changing — ./install.sh again does both : | Constant | Default | Meaning | |---|---|---| pollInterval | 0.4 | Seconds between state-dir polls. | staleAfter | 43200 | Ignore state files older than this seconds . | | File | Purpose | |---|---| ccbar.swift | The whole app AppKit, single file . | hook.sh | Claude Code hook target; writes one state file per session. | install.sh | Build + install LaunchAgent + print the hooks block. | uninstall.sh | Stop + remove the LaunchAgent and state dir. | ccbar | Compiled binary gitignored — built by install.sh . | Fragility — the idle filter is a string match. hook.sh distinguishes the ~60s idle notification from a real prompt by matching the substring waiting for your input in the notification message . This is Claude Code's current idle wording, not a stable API. If Anthropic changes that text, the idle timeout will start pulsing the bar again. The fix is one line — update the case pattern in hook.sh . Conversely, only known idle text is suppressed, so any new message defaults to pulse , never to silently hiding a real prompt. Stop is the main-agent stop only SubagentStop is a separate, unhooked event , so the bar tracks real turn boundaries, not sub-agent churn.- The bar defaults to the top edge. Switch Position → Bottom or the reverse and bump Thickness in the menu-bar menu to taste — e.g. move it off an edge where a bottom Dock or the notch would hide it. Public domain — The Unlicense /gregsramblings/claude-status-bar/blob/main/LICENSE . Do whatever you want with it, no attribution required, no warranty, no liability.