ditoo-claude-meter 0.1.0__tar.gz

ditoo_claude_meter-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+_legacy/
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/

ditoo_claude_meter-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+Initial release. Pushes Claude Code's 5h/7d usage quota to a Divoom Ditoo
+Mic's 16x16 Bluetooth display as a ring gauge with an activity-state
+creature sprite. `ditoo-meter setup` wires up a `statusLine` tap, activity
+hooks, and a launchd-managed background daemon; `ditoo-meter list-devices`
+finds the paired device. macOS only. See `docs/PROTOCOL.md` for the wire
+protocol and `docs/DECISIONS.md` for the reasoning behind the current
+architecture.

ditoo_claude_meter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nowhereman
+
+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.

ditoo_claude_meter-0.1.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.5
+Name: ditoo-claude-meter
+Version: 0.1.0
+Summary: Push Claude Code 5h/7d usage quota to a Divoom Ditoo Mic's 16x16 display over Bluetooth
+Project-URL: Homepage, https://github.com/nowheremanx/ditoo-claude-meter
+Project-URL: Repository, https://github.com/nowheremanx/ditoo-claude-meter
+Project-URL: Issues, https://github.com/nowheremanx/ditoo-claude-meter/issues
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: pyobjc-framework-iobluetooth; sys_platform == 'darwin'
+Description-Content-Type: text/markdown
+
+# ditoo-claude-meter
+
+Pushes Claude Code's 5h/7d usage quota to a [Divoom Ditoo Mic](https://divoom.com/)'s
+16x16 Bluetooth display, as a ring gauge around a small creature that reflects
+whatever Claude Code is currently doing (working / waiting / idle / asleep).
+
+```
+uv tool install ditoo-claude-meter
+ditoo-meter list-devices   # find your paired device
+ditoo-meter setup          # wire up statusLine + hooks + the background daemon
+```
+
+Full wire-protocol detail (frame format, commands, real-hardware findings)
+lives in [`docs/PROTOCOL.md`](docs/PROTOCOL.md) and is not repeated here.
+This README exists to explain the handful of design decisions that aren't
+obvious from reading the code, so that extending this project doesn't mean
+re-deriving them from scratch.
+
+## 1. Two names, one device -- the first mistake everyone makes
+
+The device answers to *two different Bluetooth names for the same physical
+unit and address*: the Classic radio calls itself `<name>-Audio`, the BLE
+radio advertises as `<name>-Light`. The display protocol lives on the
+**Classic (`-Audio`) side**, despite what the name suggests -- BLE only
+exposes a transparent-UART service that nothing in this project (or any
+known open-source Divoom project) has gotten to accept image data. If you're
+poking around with a Bluetooth scanner and see `-Light`, that's the wrong
+radio for this project's purposes; look for pairing/SDP activity on the
+`-Audio` name instead. See PROTOCOL.md's "Transport" and "Why not BLE"
+sections for the full story, including what was tried against BLE and why it
+didn't pan out.
+
+## 2. Why the Bluetooth helper is a separate subprocess
+
+`link_helper.py` runs as its own subprocess (`python -m ditoo_meter.link_helper
+<MAC>`), spoken to over stdin/stdout by `link.py`, rather than being called
+directly from the daemon. This isn't incidental complexity: `pyobjc-framework-
+IOBluetooth`'s async APIs only deliver their callbacks (RFCOMM channel open,
+incoming data, channel closed) by pumping an `NSRunLoop`. The daemon's own
+loop is a plain synchronous `while` with a `time.sleep(0.5)` -- there's no
+run loop for IOBluetooth's callbacks to arrive on. Reconciling the two in one
+process means either running IOBluetooth on a dedicated thread with its own
+run loop and shuttling data across a queue, or making the daemon's main loop
+itself run loop-driven and fighting IOBluetooth for control of it. A separate
+process sidesteps both: the helper owns an event loop it can pump freely
+(`link_helper.py`'s `_pump()`), and the daemon side (`link.py`) stays fully
+synchronous -- `ensure_connected()`, `send_burst()`, and friends are plain
+function calls with no async machinery of their own. The cost is a pipe
+protocol and a subprocess lifecycle to manage (see `link.py`'s lock-guarded
+state machine), which is a smaller problem than making two different
+concurrency models share one process.
+
+## 3. The statusLine tap passthrough contract
+
+`ditoo-meter setup` takes over `~/.claude/settings.json`'s `statusLine`
+slot, pointing it at `ditoo-meter tap`. If you already had a `statusLine`
+command configured, whatever it printed must keep printing -- this tool
+occupies the slot, it doesn't get to break your existing statusline.
+
+- **`setup`** snapshots your prior `statusLine.command` (if any) into
+  `~/.config/ditoo-claude-meter/config.json` as `passthrough`, then installs
+  its own command in its place. It has to happen at install time, once --
+  by the time `tap` is running, `statusLine` already points at us, so the
+  original command has nowhere else to be read from later.
+- **`tap`** (called by Claude Code on every statusline tick) always reads
+  the usage payload off stdin first and records it, then -- if a
+  `passthrough` command was saved -- re-invokes *that* command with the same
+  stdin and relays its stdout/stderr/exit code byte-for-byte, unmodified.
+  Whatever your original statusline displayed (formatting, colors, other
+  integrations) is not ours to reinterpret. If there's no saved passthrough,
+  or the passthrough command times out or errors, `tap` falls back to
+  printing its own compact usage line -- a stuck passthrough must not be
+  able to take Claude Code's statusline down with it.
+- **`undo`** restores the saved `passthrough` command back into
+  `statusLine` and clears the saved copy -- but only when `statusLine` still
+  actually points at us at the time `undo` runs. If you've hand-edited
+  `statusLine` since `setup` (pointing it at something else), `undo` leaves
+  it alone and *does not* discard the saved `passthrough` value, since that
+  might be the only copy of your original command; it prints a note telling
+  you where to find it in config.json instead.
+
+## 4. Why animations make the daemon simpler
+
+Real hardware finding (see PROTOCOL.md's "Multi-frame animation"): **the
+device loops a pushed animation locally and indefinitely.** Push once, it
+keeps playing until replaced -- there's no need to re-send frames on a
+timer. Every type in this codebase reflects that: `render()` always returns
+an `Animation` (a tuple of `(frame, duration_ms)` pairs), even a static
+scene is just a one-frame animation, and `protocol.commands_for()` decides
+whether that goes out as a single `0x44` image or a chunked `0x49`
+animation. The consequence that matters most for the daemon: **alert
+blinking (usage over 100%) is a real 2-frame animation, not a 500ms
+re-render loop.** The daemon hashes the animation it would push and only
+talks to Bluetooth when that hash changes from what's already on the
+device -- in steady state, with nothing to say, it sends nothing at all.
+
+## 5. Silent failure -- why pacing is insurance, not decoration
+
+`0x44` and `0x49` (the image/animation push commands) never get an ACK
+from the device. A dropped write and a successful one look identical at the
+RFCOMM layer -- silence either way. Two consequences follow directly from
+this, both load-bearing:
+
+- `link.py` waits `CHANNEL_SETTLE_S` (~1.5s, real-hardware-verified) after
+  sending the channel-switch command before it will attempt to push an
+  image. Skipping this produces a write that "succeeds" and a screen that
+  never updates.
+- `Link.send_burst()` puts a small gap between chunks of a multi-part push
+  instead of firing them back-to-back. It's the only line of defense
+  against a burst the device can't keep up with, given that there's no way
+  to ask it afterward whether the push landed.
+
+If you need positive confirmation the link is alive, `0x46` (get view) is
+the one command in this protocol that *does* reply -- see PROTOCOL.md.
+
+## A note on naming
+
+The repo/package is `ditoo-claude-meter`, the importable module is
+`ditoo_meter`, and the installed command is `ditoo-meter`. That's three
+different spellings for one project. It's intentional (PyPI package names
+can't contain underscores the way Python module names require), not an
+inconsistency to "fix" -- if you see `ditoo_meter` in an import and
+`ditoo-claude-meter` in a `pip install`, that's expected.
+
+## Linux
+
+Not implemented. `link.py`'s `Link._popen()` has an explicit branch on
+`sys.platform` where a Linux transport would plug in -- Classic SPP over
+`socket.AF_BLUETOOTH` is roughly a dozen lines (connect, then plain
+`socket.send`/`recv` instead of the IOBluetooth async dance macOS needs).
+No IOBluetooth-style run-loop problem exists on Linux, so a Linux helper
+likely wouldn't even need the separate-subprocess split described above.
+Contributions welcome.

ditoo_claude_meter-0.1.0/README.md

@@ -0,0 +1,133 @@
+# ditoo-claude-meter
+
+Pushes Claude Code's 5h/7d usage quota to a [Divoom Ditoo Mic](https://divoom.com/)'s
+16x16 Bluetooth display, as a ring gauge around a small creature that reflects
+whatever Claude Code is currently doing (working / waiting / idle / asleep).
+
+```
+uv tool install ditoo-claude-meter
+ditoo-meter list-devices   # find your paired device
+ditoo-meter setup          # wire up statusLine + hooks + the background daemon
+```
+
+Full wire-protocol detail (frame format, commands, real-hardware findings)
+lives in [`docs/PROTOCOL.md`](docs/PROTOCOL.md) and is not repeated here.
+This README exists to explain the handful of design decisions that aren't
+obvious from reading the code, so that extending this project doesn't mean
+re-deriving them from scratch.
+
+## 1. Two names, one device -- the first mistake everyone makes
+
+The device answers to *two different Bluetooth names for the same physical
+unit and address*: the Classic radio calls itself `<name>-Audio`, the BLE
+radio advertises as `<name>-Light`. The display protocol lives on the
+**Classic (`-Audio`) side**, despite what the name suggests -- BLE only
+exposes a transparent-UART service that nothing in this project (or any
+known open-source Divoom project) has gotten to accept image data. If you're
+poking around with a Bluetooth scanner and see `-Light`, that's the wrong
+radio for this project's purposes; look for pairing/SDP activity on the
+`-Audio` name instead. See PROTOCOL.md's "Transport" and "Why not BLE"
+sections for the full story, including what was tried against BLE and why it
+didn't pan out.
+
+## 2. Why the Bluetooth helper is a separate subprocess
+
+`link_helper.py` runs as its own subprocess (`python -m ditoo_meter.link_helper
+<MAC>`), spoken to over stdin/stdout by `link.py`, rather than being called
+directly from the daemon. This isn't incidental complexity: `pyobjc-framework-
+IOBluetooth`'s async APIs only deliver their callbacks (RFCOMM channel open,
+incoming data, channel closed) by pumping an `NSRunLoop`. The daemon's own
+loop is a plain synchronous `while` with a `time.sleep(0.5)` -- there's no
+run loop for IOBluetooth's callbacks to arrive on. Reconciling the two in one
+process means either running IOBluetooth on a dedicated thread with its own
+run loop and shuttling data across a queue, or making the daemon's main loop
+itself run loop-driven and fighting IOBluetooth for control of it. A separate
+process sidesteps both: the helper owns an event loop it can pump freely
+(`link_helper.py`'s `_pump()`), and the daemon side (`link.py`) stays fully
+synchronous -- `ensure_connected()`, `send_burst()`, and friends are plain
+function calls with no async machinery of their own. The cost is a pipe
+protocol and a subprocess lifecycle to manage (see `link.py`'s lock-guarded
+state machine), which is a smaller problem than making two different
+concurrency models share one process.
+
+## 3. The statusLine tap passthrough contract
+
+`ditoo-meter setup` takes over `~/.claude/settings.json`'s `statusLine`
+slot, pointing it at `ditoo-meter tap`. If you already had a `statusLine`
+command configured, whatever it printed must keep printing -- this tool
+occupies the slot, it doesn't get to break your existing statusline.
+
+- **`setup`** snapshots your prior `statusLine.command` (if any) into
+  `~/.config/ditoo-claude-meter/config.json` as `passthrough`, then installs
+  its own command in its place. It has to happen at install time, once --
+  by the time `tap` is running, `statusLine` already points at us, so the
+  original command has nowhere else to be read from later.
+- **`tap`** (called by Claude Code on every statusline tick) always reads
+  the usage payload off stdin first and records it, then -- if a
+  `passthrough` command was saved -- re-invokes *that* command with the same
+  stdin and relays its stdout/stderr/exit code byte-for-byte, unmodified.
+  Whatever your original statusline displayed (formatting, colors, other
+  integrations) is not ours to reinterpret. If there's no saved passthrough,
+  or the passthrough command times out or errors, `tap` falls back to
+  printing its own compact usage line -- a stuck passthrough must not be
+  able to take Claude Code's statusline down with it.
+- **`undo`** restores the saved `passthrough` command back into
+  `statusLine` and clears the saved copy -- but only when `statusLine` still
+  actually points at us at the time `undo` runs. If you've hand-edited
+  `statusLine` since `setup` (pointing it at something else), `undo` leaves
+  it alone and *does not* discard the saved `passthrough` value, since that
+  might be the only copy of your original command; it prints a note telling
+  you where to find it in config.json instead.
+
+## 4. Why animations make the daemon simpler
+
+Real hardware finding (see PROTOCOL.md's "Multi-frame animation"): **the
+device loops a pushed animation locally and indefinitely.** Push once, it
+keeps playing until replaced -- there's no need to re-send frames on a
+timer. Every type in this codebase reflects that: `render()` always returns
+an `Animation` (a tuple of `(frame, duration_ms)` pairs), even a static
+scene is just a one-frame animation, and `protocol.commands_for()` decides
+whether that goes out as a single `0x44` image or a chunked `0x49`
+animation. The consequence that matters most for the daemon: **alert
+blinking (usage over 100%) is a real 2-frame animation, not a 500ms
+re-render loop.** The daemon hashes the animation it would push and only
+talks to Bluetooth when that hash changes from what's already on the
+device -- in steady state, with nothing to say, it sends nothing at all.
+
+## 5. Silent failure -- why pacing is insurance, not decoration
+
+`0x44` and `0x49` (the image/animation push commands) never get an ACK
+from the device. A dropped write and a successful one look identical at the
+RFCOMM layer -- silence either way. Two consequences follow directly from
+this, both load-bearing:
+
+- `link.py` waits `CHANNEL_SETTLE_S` (~1.5s, real-hardware-verified) after
+  sending the channel-switch command before it will attempt to push an
+  image. Skipping this produces a write that "succeeds" and a screen that
+  never updates.
+- `Link.send_burst()` puts a small gap between chunks of a multi-part push
+  instead of firing them back-to-back. It's the only line of defense
+  against a burst the device can't keep up with, given that there's no way
+  to ask it afterward whether the push landed.
+
+If you need positive confirmation the link is alive, `0x46` (get view) is
+the one command in this protocol that *does* reply -- see PROTOCOL.md.
+
+## A note on naming
+
+The repo/package is `ditoo-claude-meter`, the importable module is
+`ditoo_meter`, and the installed command is `ditoo-meter`. That's three
+different spellings for one project. It's intentional (PyPI package names
+can't contain underscores the way Python module names require), not an
+inconsistency to "fix" -- if you see `ditoo_meter` in an import and
+`ditoo-claude-meter` in a `pip install`, that's expected.
+
+## Linux
+
+Not implemented. `link.py`'s `Link._popen()` has an explicit branch on
+`sys.platform` where a Linux transport would plug in -- Classic SPP over
+`socket.AF_BLUETOOTH` is roughly a dozen lines (connect, then plain
+`socket.send`/`recv` instead of the IOBluetooth async dance macOS needs).
+No IOBluetooth-style run-loop problem exists on Linux, so a Linux helper
+likely wouldn't even need the separate-subprocess split described above.
+Contributions welcome.

ditoo_claude_meter-0.1.0/docs/DECISIONS.md

@@ -0,0 +1,92 @@
+# Decisions
+
+## 2026-08-24: replaced the Swift `ditoo_send` helper with pyobjc-framework-IOBluetooth
+
+**Motivation:** shipping to PyPI as a pure-Python wheel means not depending on a
+swiftc-compiled binary. If `pyobjc-framework-IOBluetooth` can open the RFCOMM
+channel and talk to the device, a compiled Swift helper and the whole
+swiftc-in-CI/Xcode-Command-Line-Tools path can go away.
+
+**Result: confirmed working, real hardware, all 5 success criteria met.**
+The exact sequence, implemented via PyObjC selectors:
+
+1. `IOBluetoothDevice.deviceWithAddressString_(mac)`
+2. `device.openConnection()` -- baseband link, done *before* opening RFCOMM
+3. `device.performSDPQuery_(None)`, wait ~4s
+4. `device.getServiceRecordForUUID_(uuid16=0x1101)` -> `record.getRFCOMMChannelID_(None)`
+5. `device.openRFCOMMChannelAsync_withChannelID_delegate_(None, cid, delegate)` -- async, not sync
+6. Pump `NSRunLoop.currentRunLoop()` in `NSDefaultRunLoopMode` until the delegate's
+   `rfcommChannelOpenComplete_status_` fires
+7. `channel.writeSync_length_(bytes, len(bytes))`
+
+Final run: SDP resolved channel 1, async open completed with status 0 and
+MTU 666, a brightness command got a real device reply (`0x46` echo), a test
+image visibly changed the screen, and liveness probes over a 60s hold got
+replies.
+
+**Two real gotchas found beyond what was known going in -- both fixed, both
+now baked into `src/ditoo_meter/link_helper.py`:**
+
+1. **The RFCOMM delegate must be a real `NSObject` subclass.** A plain
+   Python object (not subclassing `NSObject`) crashes the process with an
+   uncaught `NSException` inside `-[OC_PythonObject forwardInvocation:]` the
+   moment `IOBluetoothRFCOMMChannel` calls back into it -- even though
+   PyObjC's "plain Python object as delegate" pattern is normally fine for
+   many AppKit/Cocoa callback APIs. Fix: subclass `Foundation.NSObject` and
+   call `objc.super(Delegate, self).init()` in a proper `init()` override.
+2. **`rfcommChannelData_data_length_`'s `data_pointer` argument arrives
+   already bridged to a Python `bytes` object**, not a raw C pointer. The
+   fix is just `bytes(data_pointer)[:length]`, not `ctypes.string_at(...)`.
+
+**A debugging detour worth recording:** early runs showed zero `RX` replies
+and no visible image change, on both pyobjc *and* a reference Swift binary
+checked directly -- so the first-pass conclusion was "device/session state
+issue, not a pyobjc gap." On the next attempt, with a freshly-idle device
+and no back-to-back rapid connect/disconnect churn from testing, both
+implementations replied cleanly and identically. The root cause of the
+earlier flakiness was never conclusively identified (worth keeping in mind:
+heavy churn from repeated manual connect/open/close cycles during
+interactive testing may leave the device slow to reply for a while -- give
+it a few seconds of quiet between manual test runs). Point for next time:
+when a real-hardware test shows a total communication blackout, check a
+reference implementation under identical conditions before concluding new
+code is at fault -- and double check any new marshalling code
+(pointer/bytes decoding) before trusting a "no data received" result.
+
+## 2026-08-24: rewrote the project from scratch for a PyPI-publishable package
+
+**Motivation:** the prior implementation (kept as `_legacy/` during the
+rewrite, not shipped) proved the protocol and the overall architecture on
+real hardware, but its structure only worked from an editable checkout:
+`Path(__file__).parents[2]` located both the `.pix` sprite assets and the
+launchd plist template relative to a source tree that doesn't exist once
+installed as a wheel, and the device MAC address was a hardcoded module
+constant rather than something `list-devices`/`setup` could discover. It
+also carried a handful of structural bugs discovered while reading the code
+closely for this rewrite -- notably a subprocess-lifecycle race in the old
+`link.py` (the reader thread's exit handling and a concurrent
+`ensure_connected()` call could each independently decide a new helper
+process was needed, orphaning one of the two), a data-loss path in
+`integrate.undo()` (it unconditionally cleared the saved passthrough
+command even when there was nothing to restore it into), and a usage-source
+resolution that let a stale `usage.json` permanently shadow a fresher
+`plan-usage-history.json` sample.
+
+**What changed, architecturally:** the biggest simplification came from a
+real-hardware finding that was already true of the protocol but not yet
+reflected in the code: the device loops a pushed animation locally and
+indefinitely. Making `Animation` (not a single `Frame`) the type `render()`
+returns everywhere let a lot of daemon-side complexity disappear outright --
+alert blinking became a genuine 2-frame animation instead of a 500ms
+re-render timer, and the daemon's steady-state Bluetooth traffic dropped to
+zero. `link.py`'s subprocess state machine was rewritten so every mutable
+field is read and written under one lock, closing the spawn race described
+above. Device discovery (`discovery.py`, backed by
+`IOBluetoothDevice.pairedDevices()`) replaced the hardcoded MAC. Packaging
+now uses `importlib.resources` for the `.pix` sprites (with a
+`~/.config/ditoo-claude-meter/art/` override directory for users who want to
+edit them without touching the installed package) and generates the launchd
+plist in-process with `plistlib.dump()` instead of templating a checked-in
+file. See `docs/PROTOCOL.md` for the protocol facts themselves, which did
+not change -- this rewrite is a structural one, not a re-verification of the
+wire format.