Busy Crew

See what your Claude Code and Codex agents are doing at a glance, on the LED strip of your BUSY Bar. Each session is a little character: working, waiting for you, or done.

Your Mac reads Claude Code and Codex activity locally and sends a 72 × 16 pixel frame to the bar. No conversation content leaves your Mac. Monitoring needs no cloud service; an optional daily check looks for releases on GitHub. Busy Crew is an independent project, not affiliated with BUSY, Anthropic or OpenAI.

What you see

When both families are active, the duo view above shows each family's count and up to four state dots. With only one family, each session gets its own character. Turn the scroll wheel to see the tokens your agents used.

Claude only	Codex only
Tokens today	Tokens this month

Token totals are shown in K (thousand), M (million) or G (billion) and include cache tokens. These captures are real, taken on the author's bar with commands like busy-crew snapshot docs/tokens-today.png --leds.

Requirements

• A Mac (macOS) and a BUSY Bar, connected by USB or Wi-Fi
• Homebrew, or Python 3.11+ and uv
• Claude Code and/or the Codex app, used on this Mac
• Optional: ccusage 20+ for the token views

Install

Choose one package manager:

brew install cmdai-hq/tap/busy-crew
# or:
uv tool install busy-crew

For a first try, connect the bar by USB. No device password is needed:

busy-crew install --address http://10.0.4.20 --timezone Europe/Paris
# Wait a few seconds for the collector to start.
busy-crew status

Replace Europe/Paris with your IANA time zone. Already-open Claude sessions may need restarting to load the new hooks.

Wi-Fi needs API access enabled and a password. Follow the installation guide for Wi-Fi, token counts, uv PATH setup and manual updates.

Update: busy-crew upgrade keeps your settings, restarts the collector and refreshes the menu icon if installed. Remove: run busy-crew uninstall, then brew uninstall busy-crew or uv tool uninstall busy-crew.

To try a checkout, see Development. Use uv run busy-crew for its commands.

Using it

A session waiting for you always brings the sessions view back. No button answers a question or grants a permission: do that in Claude or Codex.

The same from the terminal:

busy-crew view sessions   # or: tokens, month
busy-crew ack             # acknowledge the results on screen
busy-crew refresh         # recount tokens now
busy-crew snapshot front.png --leds

A ✓ counts toward its family's total until you acknowledge it, the session starts new work, or it goes away (a closed Claude process, an archived Codex conversation, or a Codex response finished more than two hours ago). How results and acknowledgment work.

Menu bar icon

Optional. The icon shows the collector's health: running, paused, degraded, stopped, or update available. Its menu shows sessions and today's tokens, and lets you acknowledge results, recount tokens, reload the collector, open the log, or install a new release.

busy-crew menubar install   # needs the Swift compiler: xcode-select --install

Icon states, actions and updates. The picture is a simulation of the real menu.

Configuration

install writes config.json in the state folder (example):

After editing config.json, choose Reload collector in the menu bar, or run:

launchctl kickstart -k gui/$UID/local.busybar.agent-deck

Over HTTP the key travels unencrypted: use a trusted network, or HTTPS if your device supports it. The busylib WebSocket SDK puts the key in a URL query and honors proxy environment variables; don't share those URLs or proxy logs.

CLAUDE_CONFIG_DIR, CODEX_HOME and BUSY_CREW_STATE (formerly AGENT_DECK_STATE, still honored) are supported. Set them before installing so the collector uses those roots and hooks write to the matching state folder.

Troubleshooting

Start with busy-crew status.

• The bar went dark: check status and the menu icon. A higher-priority app can also take the display; Busy Crew does not detect that ownership.
• Token views show ?: ccusage is missing, failed or stale; sessions still work. Follow token setup.
• busy-crew not found: check your PATH; after a uv install, run uv tool update-shell and reopen your terminal.
• invalid choice: check for an older copy with command -v busy-crew. From a checkout, use uv run busy-crew.

More, including Claude settings conflicts and recovery: troubleshooting.

How it works

• Claude Code: the session registry (~/.claude/sessions) gives each session, its state and its process; hooks sharpen "waiting for you" and finished results.
• Codex: the app's local SQLite databases and conversation logs, opened read-only.
• Tokens: one ccusage daily report from the 1st of the month, refreshed every two minutes.
• The bar: a frame through the BUSY Bar local API, with a 15-second lease so the bar recovers its own display if your Mac goes away.

Limits worth knowing: Codex approval requests are only partly visible, cloud tasks and other machines aren't tracked. Details: how it works, tested versions.

Privacy: Busy Crew sends frames to your bar and receives its button events. A daily GitHub release check can be disabled with "update_check": false. Turn events and questions may be decoded in memory; conversation text is never written to state files, logged or sent. What is read, kept and sent.

Development

git clone https://github.com/cmdai-hq/busy-crew.git
cd busy-crew
uv sync --locked
uv run python -m unittest discover -s tests -v
uv run busy-crew demo /tmp/busy-crew-demo

These commands need no bar and install no collector or hooks. The demos are fictional PNGs. Tests never contact a device, run a model or touch your real agent data.

See CONTRIBUTING for the module map, Swift tests and testing a branch on your bar. CI covers macOS and Linux on Python 3.11, 3.14 and 3.15; hardware was previously verified on firmware 1.2.4 (API 27.5.0). Security reporting.

License

MIT. Contributions are welcome; see CONTRIBUTING.

The characters are drawn in code, inspired by Clawd and Codex. References: BUSY Bar developer docs, busylib, Claude Code hooks, ccusage.