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 and no cloud service is involved. 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 on the same network
• 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

brew install cmdai-hq/tap/busy-crew   # or: uv tool install busy-crew
busy-crew install --address http://busybar.local --timezone Europe/Paris
busy-crew status

Use your bar's address. Your agents appear on the bar within a few seconds.

Updating: brew update && brew upgrade busy-crew or uv tool upgrade busy-crew, then busy-crew install, which keeps your settings, refreshes the LaunchAgent and hooks and restarts the collector. If you use the menu bar icon, run busy-crew menubar install too. Removing: run busy-crew uninstall first, then brew uninstall busy-crew or uv tool uninstall busy-crew.

From a checkout, to contribute or try unreleased changes, prefix every command in this README with uv run, and update with git pull --ff-only && uv sync --locked before the same install:

git clone https://github.com/cmdai-hq/busy-crew.git
cd busy-crew
uv sync --locked
uv run busy-crew install --address http://busybar.local --timezone Europe/Paris

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. When the bar goes dark, the icon in your macOS menu bar says why: running, paused by the selector, degraded, stopped, or waiting for a reload after an update. Its menu shows each family's 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):

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, which pins them in the LaunchAgent and the hook command.

Troubleshooting

Start with busy-crew status.

• The bar went dark: check status first. The collector may have stopped, or it is running while the selector is on Off or Settings, or a higher-priority app owns the display. The menu bar icon tells these apart at a glance.
• Token views show ?: ccusage is missing or failed; sessions still work. Set ccusage in config.json.
• busy-crew not found, or invalid choice: you're running an older copy. Update it as above; from a checkout, use uv run busy-crew. The pre-1.0 agent-deck command still works.

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 talks to your bar: frames, display cleanup and its button events, with the bar's API key if you set one. Once a day it asks GitHub for the number of its latest release; "update_check": false turns that off. Apart from turn events and the questions an agent asks you, conversation content is never parsed, and nothing from it is stored, logged or sent. What is read, kept and sent.

Development

uv sync --locked
uv run python -m unittest discover -s tests -v
uv run busy-crew run              # run the collector in the foreground
uv run busy-crew demo /tmp/demo   # fictional previews of each layout

The tests never contact a device, run a model or touch your real agent data. CI runs them on macOS and Linux with Python 3.11, 3.14 and 3.15. Verified on BUSY Bar firmware 1.2.4 (API 27.5.0). To develop on the Mac that runs your bar, keep the Homebrew copy installed and follow Developing on the Mac that runs your bar. See CONTRIBUTING and SECURITY.

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.