← back to dossier
OPEN SOURCEAPACHE-2.0MACOS 13+BUILT FOR CLAUDE CODE
GitHub ↗Install

Hive Light

See what needs you, at a glance.

Menu-bar icon states: needs you (red), working (orange), idle (green), no sessions (dim).
The menu-bar icon reflects the most urgent state across all your sessions.
LICENSEAPACHE 2.0MACOS13+SWIFT5.9+RELEASEV0.27.2MADE FORCLAUDE CODE

00 · THE NAME

hive light, n.

/ˈhaɪv ˌlaɪt/ — noun

  1. 1. the single glow by which a colony of many independent workers can be read as one organism; the state of the whole, never of any one bee.
  2. 2. the glance a beekeeper gives the hive — the work is left to happen on its own, and the keeper steps in only when something truly needs them.
  3. 3. (software, macOS) a menu-bar light that distills every Claude Code session on your Mac — projects as cells, sessions within them, subagents fanning out like foragers — into one traffic light: red when a session needs you, orange while the hive hums, green when all is quiet.

A hive is never managed one bee at a time.

01 · WHAT IT IS

One light for every session

Hive Light is a native macOS menu-bar app that watches every Claude Code session on your Mac and distills them into a single traffic light. One glance tells you whether an agent is waiting on you, still working, or done — no alt-tabbing through terminals to find out.

02 · THE LIGHT

Four states, zero ambiguity

Red

A session needs you: a question, permission prompt, or review request is waiting.

Blinks (question) · steady (permission, review)

Orange

At least one session is actively working.

Gentle pulse

Green

Sessions are idle; nothing needs you.

Steady

Hollow

No live sessions.

Steady

Click the icon for the full picture: a one-line summary such as 1 needs you · 2 working, every live session sorted by urgency, and settings — subagents, launch at login, notifications, one-click hook install or removal.

03 · HOW IT WORKS

Filesystem events, not polling

  1. 1. Hook shim. A small shim registers into Claude Code's hooks — installed and removed with one click from the app.
  2. 2. Session state. On each hook event, the shim writes that session's state to ~/.hive-light/sessions/.
  3. 3. Live display. The app watches that folder and updates the light the moment anything changes — within a fraction of a second.

04 · WHY USE IT

Built to stay out of the way

Native, and nothing else

A lightweight Swift menu-bar app — no dock icon, no window, no Electron. The icon adapts to light and dark menu bars.

No polling, no network, no telemetry

Everything happens on your machine via filesystem events. The display reacts within a fraction of a second of a session changing state.

Red always wins

The light aggregates any number of concurrent sessions, sorted by urgency — a single waiting session is never buried behind busy ones.

Zero configuration

One-click install and removal of the Claude Code hooks, a launch-at-login toggle, and opt-in notifications when a session flips to needs-you.

05 · INSTALL

Get it running

Homebrew is the recommended path — updates arrive through brew upgrade. Requires macOS 13+.

TERMINAL
brew tap fr1j0/hive-light
brew trust fr1j0/hive-light  # newer Homebrew requires trusting third-party taps
brew install --cask hive-light

Or download the .app from GitHub Releases ↗ and verify the published SHA-256 checksum. Releases are currently ad-hoc signed while Apple notarization is pending, so Gatekeeper may report a downloaded app as "damaged" — clear the quarantine flag (xattr -d com.apple.quarantine) and launch again. Homebrew installs are not affected.