busy-crew 1.1.0__tar.gz

busy_crew-1.1.0/.github/workflows/release.yml

@@ -0,0 +1,89 @@
+name: Release
+on:
+  release:
+    types: [published]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - name: Check that the tag matches the package version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(uv version --short)
+          if [ "${TAG#v}" != "$version" ]; then
+            echo "Release tag $TAG does not match version $version in pyproject.toml" >&2
+            exit 1
+          fi
+      - run: uv sync --locked
+      - run: uv run python -m unittest discover -s tests
+      - run: uv build
+      - run: python3 -I tests/dist_contents.py dist
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+  pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/project/busy-crew/
+    permissions:
+      id-token: write  # Trusted publishing: no stored PyPI token.
+    steps:
+      - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+  homebrew:
+    needs: pypi
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: cmdai-hq/homebrew-tap
+          path: tap
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+      - name: Point the formula at the PyPI release
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: uv run --locked python scripts/homebrew_formula.py tap/Formula/busy-crew.rb "${TAG#v}" uv.lock
+      # Safe to re-run: an update already on main stops here, and the branch and pull request are reused.
+      - name: Open the tap pull request, merged once its tests pass
+        working-directory: tap
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version="${TAG#v}"
+          branch="busy-crew-$version"
+          if git diff --quiet; then
+            echo "The tap's main already has busy-crew $version"
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git switch -C "$branch"
+          git commit -am "busy-crew $version"
+          git push --force origin "$branch"  # This bot owns the branch; a re-run replaces its own commit.
+          if [ "$(gh pr view "$branch" --json state --jq .state 2>/dev/null)" != "OPEN" ]; then
+            gh pr create --base main --head "$branch" --title "busy-crew $version" \
+              --body "Release https://github.com/cmdai-hq/busy-crew/releases/tag/$TAG, from its PyPI sdist and uv.lock."
+          fi
+          gh pr merge "$branch" --auto --squash --delete-branch

busy_crew-1.1.0/.github/workflows/test.yml

@@ -0,0 +1,33 @@
+name: Test
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ['3.11', '3.14', '3.15']  # 3.15: Homebrew's python@3.15
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+      - run: uv sync --locked --python '${{ matrix.python }}'
+      - run: uv run python -m unittest discover -s tests -v
+      - name: Build and smoke test the installed wheel outside the repository
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.11'
+        shell: bash
+        run: |
+          uv build
+          python3 -I tests/dist_contents.py dist
+          uv venv "$RUNNER_TEMP/agent-deck-wheel" --python 3.11
+          uv pip install --python "$RUNNER_TEMP/agent-deck-wheel/bin/python" dist/*.whl
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/agent-deck-wheel/bin/busy-crew" --help
+          "$RUNNER_TEMP/agent-deck-wheel/bin/agent-deck" --help  # pre-1.0 alias
+          "$RUNNER_TEMP/agent-deck-wheel/bin/busy-crew" demo "$RUNNER_TEMP/agent-deck-demo"
+          "$RUNNER_TEMP/agent-deck-wheel/bin/python" -I "$GITHUB_WORKSPACE/tests/wheel_smoke.py"

busy_crew-1.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.DS_Store
+*.egg-info/
+dist/
+.env
+state/
+.playwright-mcp/

busy_crew-1.1.0/CHANGELOG.md

@@ -0,0 +1,85 @@
+# Changelog
+
+## 1.1.0 — 2026-10-11
+
+- Install without a checkout: `brew install cmdai-hq/tap/busy-crew` or
+  `uv tool install busy-crew`, then `busy-crew install`. Each GitHub release
+  now publishes the package to PyPI and updates the Homebrew formula.
+- Offer new releases: once a day the collector asks GitHub for the latest
+  release (no credentials, no data about your agents; `"update_check": false`
+  in `config.json` turns it off). The menu bar icon then shows "Version X
+  available" and **Update to X**, which runs the new `busy-crew upgrade`:
+  `brew upgrade` or `uv tool upgrade`, then `install` with the new version and
+  a reinstall of the menu bar app. A failed check never degrades the status.
+- `install` and `menubar install` write an interpreter path that survives
+  package upgrades: inside Homebrew's versioned `Cellar` folder, they use the
+  formula's `opt` link instead. `--python` or `BUSY_CREW_PYTHON` choose
+  another interpreter, and `install` checks that it can run Busy Crew before
+  changing anything.
+- The README describes the Homebrew, uv and checkout installs, and its links
+  work on the PyPI page.
+
+## 1.0.1 — 2026-10-11
+
+- A Codex conversation with a journal line over 2 MB (a large tool output)
+  no longer shows `?` for the whole Codex family for up to a day: the line is
+  left out of the turn. Turn events and function calls that large still fail
+  the read.
+- An unreadable Codex journal is no longer rescanned every second until it
+  changes, and the service log names why a source failed.
+- Read less: Codex journal records that cannot change a turn (messages,
+  reasoning, tool calls other than questions, tool outputs) are recognized from
+  their first bytes and never decoded, which also makes reading about four times faster; only the
+  needed Codex columns are queried. Claude hook fingerprints are keyed with a
+  per-installation secret (fingerprints recorded before the upgrade are migrated), and `front.png` and `service.lock` are private.
+- Document what Busy Crew reads, keeps and sends in
+  [PRIVACY](docs/privacy.md).
+
+## 1.0.0 — 2026-10-11
+
+First public release, under the MIT License.
+
+- Rename the command to `busy-crew`, the package to `busy-crew` and the menu
+  bar app to Busy Crew. `agent-deck` stays as an alias and `AGENT_DECK_STATE`
+  is still honored next to `BUSY_CREW_STATE`. New installations use
+  `~/Library/Application Support/BusyCrew`; existing ones keep their folder,
+  LaunchAgent and hooks. After pulling, run `uv sync --locked` to get the new
+  command, and `uv run busy-crew menubar install` to rename the menu bar app.
+- License the project under MIT instead of PolyForm Noncommercial.
+- Add a month-to-date token view: Start / Pause cycles sessions, today and
+  this month, and the scroll wheel steps between them. Each token view names
+  its period at the bottom.
+- Treat a finished or failed Codex conversation silent for two hours as dead:
+  it leaves the count with its `✓`, instead of piling up until acknowledged.
+- Keep open Claude sessions visible after work completes and after acknowledgment;
+  show a sleeping indicator when the Claude family is entirely idle.
+- Isolate global hook imports, record owned hook commands, respect custom roots,
+  and make installation conflicts/failures recoverable.
+- Refuse credential-bearing redirects and scope display cleanup to Busy Crew.
+- Validate local source and command data, isolate malformed records, and preserve
+  successful completion identities across monitor restarts.
+- Correlate pending interactions, recover long-turn boundaries, and distinguish
+  failed/aborted work from successful responses.
+- Limit acknowledgment to displayed results, recover from WebSocket closure and
+  token-worker errors, bound commands/logs, and close SQLite connections promptly.
+- Add macOS/Python CI, package metadata, wheel smoke tests and recovery/security
+  documentation. Adapter versions and limitations are listed in
+  [COMPATIBILITY](docs/COMPATIBILITY.md).
+- Verify Claude process identity through libproc on macOS instead of forking `ps`
+  every poll, keeping `ps` as the fallback where libproc is unavailable; skip
+  fsync for the per-poll status snapshot and rewrite `front.png` only when the
+  frame changes.
+- Center the Codex character on Clawd in the duo view and keep its face visible
+  when dimmed.
+- Add an optional macOS menu bar icon (`uv run busy-crew menubar install`) showing the
+  collector's health (stopped, degraded, update available, paused), with
+  acknowledge, reload and open-log actions. The collector publishes `health`,
+  `code_changed`, `pid` and `started_at` in `status.json`.
+- Add `agent-deck refresh` and a **Refresh tokens now** menu bar action to recount
+  today's tokens immediately, instead of waiting up to two minutes. The menu also
+  shows the token totals and when they were counted.
+
+## 0.1.0
+
+Initial local Claude/Codex front-display monitor, controls and optional daily
+ccusage token view. No remote-machine tracking.

busy_crew-1.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+Forks, bug reports, and pull requests are welcome. By submitting a
+contribution, you agree to license it under the project's [MIT License](LICENSE).
+You retain your copyright and must have the right to submit the contribution
+under these terms.
+Keep any required third-party license and copyright notices intact.
+
+Use Python 3.11 or newer and [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv sync --locked
+uv run python -m unittest discover -s tests -v
+uv build
+```
+
+Tests must use temporary directories and synthetic Claude/Codex data. Mock
+launchctl, processes, network requests and the device. Do not install hooks,
+restart the user's service, modify real agent databases or contact a BUSY Bar
+from tests. Keep conversation contents, IDs, local paths, API tokens and runtime
+files out of commits, issue attachments and test fixtures.
+
+For changes to an adapter, include a regression covering its observable result
+and failure behavior. Record the tested source version and distinguish internal
+file formats from supported public APIs. For render changes, generate the
+fictional previews with `uv run busy-crew demo /tmp/busy-crew-demo` and inspect
+them at the native 72 × 16 resolution as well as enlarged. The README images in
+`docs/` are real captures (for example `uv run busy-crew snapshot docs/tokens-today.png --leds`); do not overwrite them
+with fictional previews.
+
+CI tests Linux and macOS on Python 3.11, 3.14 and 3.15. Device integration and real
+LaunchAgent lifecycle checks require an explicitly chosen test device/account;
+unit tests and wheel smoke tests do not establish those results.
+
+## Releasing
+
+1. In a pull request, bump `version` in `pyproject.toml`, run `uv lock`, and
+   move the CHANGELOG's "Unreleased" notes under the new version.
+2. Merge it, then publish a GitHub release whose tag is `v` plus that version
+   (`gh release create v1.2.3 --generate-notes` or the web form).
+3. The Release workflow does the rest. It checks that the tag matches the
+   version, tests, builds and publishes to PyPI. Then it opens a pull request on
+   [cmdai-hq/homebrew-tap](https://github.com/cmdai-hq/homebrew-tap) that points
+   the formula at the new sdist and regenerates its resources from `uv.lock`.
+   That pull request merges itself once `brew test-bot` passes.
+4. Installed copies see the release within a day (see
+   [docs/privacy.md](docs/privacy.md)) and offer **Update to X** in the menu
+   bar icon.
+
+Before the first release, set up:
+
+- the `pypi` environment in this repository, with required reviewers;
+- a PyPI trusted publisher for `busy-crew`: owner `cmdai-hq`, repository
+  `busy-crew`, workflow `release.yml`, environment `pypi`;
+- a `HOMEBREW_TAP_TOKEN` secret: a fine-grained token limited to
+  `cmdai-hq/homebrew-tap`, with read and write access to contents and pull
+  requests;
+- on `cmdai-hq/homebrew-tap`: **Allow auto-merge** in the settings, and a
+  branch rule on `main` that requires the `test-bot (macos-latest)` check.
+  Without the required check, auto-merge does not wait for `brew test-bot`.
+
+Re-running a failed Release job is safe: the tap step reuses its branch and
+pull request, and stops if the tap already has the version.

busy_crew-1.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tristan Bessoussa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

busy_crew-1.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: busy-crew
+Version: 1.1.0
+Summary: Claude and Codex sessions on a BUSY Bar's front LED display
+Project-URL: Homepage, https://github.com/cmdai-hq/busy-crew
+Project-URL: Issues, https://github.com/cmdai-hq/busy-crew/issues
+Project-URL: Source, https://github.com/cmdai-hq/busy-crew
+Project-URL: Changelog, https://github.com/cmdai-hq/busy-crew/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: busy-bar,claude-code,codex,led,macos,menu-bar,status
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: busylib==2.6.0
+Requires-Dist: pillow==12.3.0
+Description-Content-Type: text/markdown
+
+# Busy Crew
+
+**See what your Claude Code and Codex agents are doing at a glance, on the LED strip of your [BUSY Bar](https://busy.app).** Each session is a little character: working, waiting for you, or done.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cmdai-hq/busy-crew/main/docs/busy-bar.jpg" width="576" alt="A BUSY Bar running Busy Crew: 4 Claude sessions and 3 Codex conversations, with their states">
+</p>
+
+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.
+
+<table>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/cmdai-hq/busy-crew/main/docs/claude-team.png" width="360" alt="Claude only: one working session, four finished, +2 more"><br>Claude only</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/cmdai-hq/busy-crew/main/docs/codex-team.png" width="360" alt="Codex only: one working, one finished, one failed"><br>Codex only</td>
+  </tr>
+  <tr>
+    <td align="center"><img src="https://raw.githubusercontent.com/cmdai-hq/busy-crew/main/docs/tokens-today.png" width="360" alt="Tokens today: Claude 1.0G, Codex 396M"><br>Tokens today</td>
+    <td align="center"><img src="https://raw.githubusercontent.com/cmdai-hq/busy-crew/main/docs/tokens-month.png" width="360" alt="Tokens this month: Claude 9.1G, Codex 1.7G"><br>Tokens this month</td>
+  </tr>
+</table>
+
+| On the bar | Meaning |
+| --- | --- |
+| Terracotta (Claude) or blue (Codex), legs moving | Working |
+| Yellow `!` | Waiting for you: a question or a permission |
+| Green `✓` | Finished, not yet acknowledged |
+| Gray, `zzz` | Open but idle Claude session; `zzz` when all of them are |
+| Gray `?` | Failed turn, unknown state or unreadable source |
+| `+N` | More sessions than the six slots |
+
+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](https://busy.app) on the same network
+- [Homebrew](https://brew.sh), or Python 3.11+ and [uv](https://docs.astral.sh/uv/)
+- [Claude Code](https://code.claude.com) and/or the [Codex app](https://openai.com/codex/), used on this Mac
+- Optional: [ccusage](https://ccusage.com/) 20+ for the token views
+
+## Install
+
+```sh
+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 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](#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`:
+
+```sh
+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
+```
+
+<details>
+<summary>What <code>install</code> changes on your Mac</summary>
+
+- **A LaunchAgent** (`local.busybar.agent-deck`) starts the collector at login and restarts it if it exits. It runs the interpreter given to `install` with `--python` or `BUSY_CREW_PYTHON`, else the Python that ran `install`. From a checkout, that is the checkout's environment, so **keep the repository folder where it is**. From a Homebrew package, it is the formula's `opt` path, which survives upgrades.
+- **Claude Code hooks**, added to Claude's settings after a private backup. They record only status identifiers and timestamps, never prompts, and never block Claude. Existing hooks and settings are preserved; a conflicting edit fails with recovery copies. Use `--no-claude-hooks` to rely on Claude's session registry alone, with coarser waiting and result detection.
+- **A private state folder**, `~/Library/Application Support/BusyCrew`, for the configuration, backups and the log. Installations made before 1.0 keep `BusybarAgentDeck`.
+
+Re-running `install` keeps the saved address and time zone unless you pass new ones. `busy-crew uninstall` removes the LaunchAgent and the hooks, and keeps the state folder.
+</details>
+
+## Using it
+
+| On the bar | Action |
+| --- | --- |
+| **Start / Pause** | Cycle: sessions → tokens today → tokens this month |
+| **Scroll wheel**, turn | One view forward (+) or back (−) |
+| **Scroll wheel**, press | Acknowledge the `✓` on screen |
+| **Back** | Return to sessions |
+| Selector on Off or Settings | Pause the display |
+
+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:
+
+```sh
+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](https://github.com/cmdai-hq/busy-crew/blob/main/docs/how-it-works.md#results-and-acknowledgment).
+
+### 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.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/cmdai-hq/busy-crew/main/docs/menu-bar.png" width="540" alt="Busy Crew's menu, open from the macOS menu bar: Running, started 6 minutes ago; Claude 1 working, 2 done, 1 idle; Codex 3 working, 1 done; today's tokens; Acknowledge results, Refresh tokens now, Reload collector, Open log, Quit menu icon">
+</p>
+
+```sh
+busy-crew menubar install   # needs the Swift compiler: xcode-select --install
+```
+
+[Icon states, actions and updates](https://github.com/cmdai-hq/busy-crew/blob/main/docs/menu-bar.md). The picture is a simulation of the real menu.
+
+## Configuration
+
+`install` writes `config.json` in the state folder ([example](https://github.com/cmdai-hq/busy-crew/blob/main/docs/config.example.json)):
+
+| Key | Purpose |
+| --- | --- |
+| `address` | The bar's URL, e.g. `http://busybar.local` |
+| `timezone` | Time zone for "today" and "this month" |
+| `ccusage` | Absolute path to `ccusage`, if the LaunchAgent cannot find it |
+| `token` | The bar's local API key, if LAN access requires one |
+| `update_check` | `false` stops the daily check for a new release on GitHub |
+
+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](https://github.com/cmdai-hq/busy-crew/blob/main/docs/menu-bar.md) 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](https://github.com/cmdai-hq/busy-crew/blob/main/docs/troubleshooting.md).
+
+## 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](https://github.com/cmdai-hq/busy-crew/blob/main/docs/how-it-works.md), [tested versions](https://github.com/cmdai-hq/busy-crew/blob/main/docs/COMPATIBILITY.md).
+
+**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](https://github.com/cmdai-hq/busy-crew/blob/main/docs/privacy.md).
+
+## Development
+
+```sh
+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). See [CONTRIBUTING](https://github.com/cmdai-hq/busy-crew/blob/main/CONTRIBUTING.md) and [SECURITY](https://github.com/cmdai-hq/busy-crew/blob/main/SECURITY.md).
+
+## License
+
+[MIT](https://github.com/cmdai-hq/busy-crew/blob/main/LICENSE). Contributions are welcome; see [CONTRIBUTING](https://github.com/cmdai-hq/busy-crew/blob/main/CONTRIBUTING.md).
+
+The characters are drawn in code, inspired by Clawd and Codex. References: [BUSY Bar developer docs](https://docs.busy.app/bar/dev), [busylib](https://github.com/busy-app/busylib-py), [Claude Code hooks](https://code.claude.com/docs/en/hooks), [ccusage](https://ccusage.com/).