Beeplight
中文 Install

Free and open source · for macOS

Know the moment
Claude needs you.

Beeplight is a status light in your menu bar for every Claude Code session and agent on your Mac. Start a task and go do something else: it tells you when Claude is waiting for you or done, and one click takes you back to the right window.

$ brew install derek920/tap/beeplight
Download for Mac

macOS 14 or later · Apple silicon and Intel · Apache-2.0

Three lights. No setup.

Beeplight checks every session three times a second and sorts it into one of three columns. It reads Claude Code's own session files, so there are no hooks to install and nothing in your settings changes.

Doing

Claude is working

A blue spinner and a count in the menu bar. It includes turns that ended while Claude waits for background work.

Waiting

Claude needs you

A permission prompt, a question or a dialog. The raised hand turns red when a task has been waiting for more than three minutes.

Done

The turn is over

With a verdict: delivered, or not, counting API errors and interruptions. New finishes stay marked until you've seen them.

Everything you'd check by hand,
in one glance.

Click to jump

One click opens the exact iTerm2 or Terminal tab, the Claude desktop session, or the editor window where the task lives. Background sessions attach, and closed ones come back with claude --resume.

  • iTerm2exact tab
  • Terminalexact tab
  • Claude desktopexact session
  • VS Code · Cursor · Traeproject window
  • claude --bgattaches
  • Closed sessionresumes

Titles that follow the work

A short title for what each session is doing now, not the first thing you typed, plus a verdict for every turn.

Usage and limits

Your 5-hour and weekly limits, how fast you're using them, and how much each session used, with a warning before you run out. Details ›

Unread finishes

A task that just finished stays marked, like an unread message, until you open it or switch to its terminal tab.

An island in the notch

It grows out of the MacBook notch; on other screens it's a pill you can drag anywhere. Hover for the list. It pops open when a task finishes or needs you, and can stay out of sight until then.

Timeline and today

A colored timeline for each task, time spent working and waiting for you, and today's totals.

Notifications

When a task needs you, finishes or fails. The notification's button jumps straight to it.

  • Subagents appear under the session that started them.
  • Background sessions started with claude --bg are tracked too.
  • English and Simplified Chinese, task titles included.
  • A web board at localhost:7333 with the same live data.
  • CPU use of the whole Mac, of Claude Code and of Beeplight itself, at the bottom of the panel and the board.
  • Every setting in Settings → Advanced, each with its default and a short explanation.

See where your limit went.

Click the 5-hour or weekly limit card for the details: how the limit filled up, where the current pace takes it by the reset, and what used it.

  • The limit over timeAnthropic's own readings through the window, and a dashed line at the current rate until the reset.
  • Usage, step by stepBars of 10 min, 30 min or 1 hour for the 5-hour window; 1 hour, 6 hours or 1 day for the week. Point at one to see what went into it.
  • Where it wentBy model, token type, project and session; click a session to jump to it. It opens on the web board and a paired phone too.

Make it yours.

Five presets, six menu bar styles, and a character that keeps you company when nothing is running.

Menu bar styles

Shown with 1 waiting, 2 running and 1 new finish.

  • Pills
  • Traffic lights
  • Radar
  • Energy bar
  • Terminal text
  • Dot

Presets

Each sets the theme, menu bar style, island and motion at once.

  • Native macOS
  • Neon
  • W1 D2 ✓1▌Terminal
  • Hologram
  • Minimal

A character for the quiet moments

When nothing is running, waiting or new, the menu bar and the island show your character. Its color and energy follow how much usage limit you have left: green and lively with plenty left, amber past half, red and drowsy near the end. Now and then the robot whirls its antenna.

  • Robot
  • Dog
  • Cat
  • Terminal cat
  • Terminal dog

Make your own: themes, presets and characters are JSON packs, so adding one is an edit to a file, not to the code. The pack format

Glance from across the room.

Turn on Phone Access and your phone becomes a status screen next to your Mac: the time, what's going on, your limits and the tasks that need you. The light follows the state, and your character keeps you company.

  • Paired with a QR code, served only on your Wi-Fi.
  • Nothing to install: add the page to your home screen.
  • Tap a task to open it on the Mac, or a limit for its details.
  • Works on iPhone and Android, upright or on its side.
Coming soon

Beeplight for iPhone

A companion app on the App Store with home and lock screen widgets, and a Live Activity that keeps running and waiting tasks in the Dynamic Island.

Runs on your Mac. Stays on your Mac.

No accounts, no telemetry

No sign-up, analytics or update checks. The service listens only on 127.0.0.1, and phone access stays off until you turn it on.

Read-only

Beeplight reads Claude Code's files under ~/.claude and the process list. It never writes there and installs no hooks. Its own history (titles, verdicts, timelines) is kept for 30 days at most, and Settings → Advanced can clean it up any time.

Exactly one thing leaves

To write titles and verdicts, it sends an excerpt of each session's recent conversation to Claude Haiku through your own claude login. That counts toward your usage, like any Claude Code request.

Every Mac, one board

Run a relay of your own and each of your Macs shows the others' tasks. Summaries are end-to-end encrypted with AES-256-GCM; the relay never sees titles or states.

Install in one line.

brew install derek920/tap/beeplight
open -a Beeplight

Updates come with brew upgrade.

You need

macOS 14 Sonoma or later, and Claude Code installed and logged in.

On first use

macOS asks to allow notifications, and to let Beeplight control iTerm2 or Terminal the first time you jump to a tab.

Questions

Is Beeplight free?

Yes. The Mac app, the web board and the relay are free and open source under the Apache License 2.0. The upcoming iPhone app will be a paid companion on the App Store.

Does it change my Claude Code setup?

No. Beeplight reads Claude Code's own session files and transcripts. It doesn't install hooks or edit your settings, and quitting it leaves nothing behind.

Does it use my Claude usage?

A little. Titles and verdicts come from Claude Haiku through your own claude login, once when a turn starts, once when it ends, and every 5 minutes during long turns. On a Claude subscription that counts toward your plan's limits; with an API key it costs about $0.001 per call.

Will it slow my Mac down?

See for yourself: the CPU line at the bottom of the panel shows the whole Mac, Claude Code and Beeplight side by side. Beeplight reads only what's new in Claude Code's files, the app redraws only what changed, and the character rests between its moves.

Can I change how it works?

Settings → Advanced lists every setting with its default: the model for titles, how long finished tasks stay on the board, how often limits are checked, how long history is kept and more. Most changes apply within a second. Without the app, put them in config.json.

Which terminals and editors can it jump to?

iTerm2 and Terminal down to the exact tab, the Claude desktop app down to the session, and VS Code, Cursor, Trae and similar editors to the project window. Sessions inside tmux can't be located yet.

Can I see sessions from my other Macs?

Yes, through a relay you run yourself. Each Mac encrypts its summary before uploading it, and only your devices hold the key. File paths, prompts, conversations and usage are never shared.

How is it different from notch apps and usage meters?

Beeplight puts three things in one place: the status of every session wherever it runs (terminal, Claude desktop or editor), your usage limits, and a phone screen that shows both. It needs no hooks, and it's open source.

Will a Claude Code update break it?

It can. Beeplight relies on Claude Code's internal session files, which may change between versions. When they do, Beeplight gets an update.

Is Beeplight made by Anthropic?

No. Beeplight is an independent project, not affiliated with or endorsed by Anthropic.

Start a task. Walk away.

Beeplight will let you know.

$ brew install derek920/tap/beeplight
View on GitHub