nimbus-notify 1.0.0__tar.gz

nimbus_notify-1.0.0/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "nsnotify",
+  "version": "0.1.0",
+  "description": "Nimbus Notify — LED ring status indicator for concurrent AI coding-agent sessions (Claude Code, Codex, Mistral Vibe).",
+  "author": { "name": "Roy Darnell" }
+}

nimbus_notify-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install + test
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m pip install -e .
+          python -m pip install pytest
+          python -m build
+          python -m twine check dist/*
+          pytest -q

nimbus_notify-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,52 @@
+name: Publish to PyPI
+
+# Publishes nimbus-notify to PyPI via Trusted Publishing (OIDC) — NO stored token.
+# Prereq (one-time, on pypi.org): Account -> Publishing -> add a "pending publisher"
+#   project: nimbus-notify | owner: ristllin | repo: nimbus-notify
+#   workflow: publish.yml   | environment: pypi
+# Then this runs on every published GitHub Release.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:   # manual trigger (build-only; publish still gates on a release env)
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build
+        run: |
+          python -m pip install --upgrade build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI (Trusted Publishing)
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release'
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nimbus-notify
+    permissions:
+      id-token: write   # OIDC token for Trusted Publishing — this is the auth
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

nimbus_notify-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.venv/
+*.env
+.pytest_cache/

nimbus_notify-1.0.0/CHANGELOG.md

@@ -0,0 +1,122 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/);
+versioning follows the convention described in
+[CONTRIBUTING.md](CONTRIBUTING.md#versioning) (semver-for-0.x pre-1.0).
+
+## [1.0.0] — 2026-07-12
+
+### Changed
+
+- **Renamed the pip distribution `nsnotify` → `nimbus-notify`** (brand alignment
+  with the Nimbus device) and the console script `nsnotify-broker` →
+  `nimbus-notify-broker`. The import package stays **`notify`** and the Claude
+  Code plugin/skill names are unchanged. The nsn wire protocol is untouched.
+- **First PyPI release** — `pip install nimbus-notify` (published via GitHub
+  Actions Trusted Publishing).
+
+### Added
+
+- `nimbus-notify-broker --install-service` / `--uninstall-service`: install the
+  broker as an auto-starting service (macOS launchd / Linux systemd user unit) so
+  it survives a reboot. Wired into `/nsnotify-setup` after the one-time
+  foreground BLE bond.
+
+## [0.4.1] — 2026-07-04
+
+### Changed
+
+- Corrected the BLE bonding docs + broker hint to match reality. The Nimbus
+  firmware bonds via macOS **"Just Works"** (encrypted + bonded, no passkey to
+  type) — not a MITM passkey, because macOS won't surface a passkey dialog for a
+  custom peripheral paired by the broker. Two gotchas are now documented: Nimbus
+  never appears in the System Settings Bluetooth list (it's a custom peripheral),
+  and the **first** bond must be made with the broker in the **foreground** — a
+  fully detached (`nohup … &`) process can't complete it. Once bonded it's
+  transparent and can run backgrounded. (Verified end-to-end on hardware.)
+
+## [0.4.0] — 2026-07-04
+
+### Changed
+
+- **The BLE link now requires a one-time pairing.** The Nimbus firmware secured
+  its GATT server (bonded + MITM passkey), so the broker writes FRAME **with
+  response** (`response=True`): an unbonded write returns an insufficient-
+  encryption error, which is what makes macOS raise its native pairing sheet.
+  Pair once — System Settings > Bluetooth, enter the 6-digit code shown on the
+  device screen (also on its serial console) — and every session after is
+  transparent. First-run gets a clear "pair first" hint on the broker console.
+
+### Fixed
+
+- After the unbonded write is rejected, the broker now **re-drives the pending
+  frame** on a short timer until the link encrypts (macOS upgrades the *same*
+  connection in place with no reconnect, so nothing else would re-send it) — the
+  ring no longer stays stale through the pairing window.
+- `_is_encryption_error` narrowed so it no longer swallows a bare ATT
+  "insufficient resources" (transient) or "not permitted" (config) as a pairing
+  failure — those must surface, not be silently dropped on a bonded link.
+- The "pair first" hint re-arms on each reconnect (was suppressed forever after
+  the first emission).
+
+## [0.3.0] — 2026-07-03
+
+### Fixed
+
+- **Vibe sessions are now detected.** The broker never started the
+  `VibeWatcher`, so Vibe sessions (which have no start/stop hook — only
+  `before_tool`/`after_tool`/`post_agent_turn`) were invisible: they never
+  appeared on the ring and never cleared. The broker now starts the watcher on
+  `~/.vibe/logs/session/` and routes `before_tool`/`after_tool` timing into its
+  HITL-inference tracker. Verified end-to-end: a real `vibe -p` session now
+  shows `start → running (tool) → done` on the device.
+- `VibeWatcher.start()` no longer bails permanently when
+  `~/.vibe/logs/session/` doesn't exist yet — on a fresh Vibe install that
+  directory is created only on the first session, so the watcher now starts as
+  long as `~/.vibe/` is present and picks up the session dir when it appears.
+
+### Changed
+
+- `Broker.handle_event` is now serialized with a lock: it is called from both
+  the asyncio socket handler (led-report events) and the VibeWatcher daemon
+  thread, so the segment allocator / sequence counter / frame push can no
+  longer interleave.
+
+## [0.2.0] — 2026-07-03
+
+### Added
+
+- `nimbus-notify-broker --ble-name <NAME>`: connect only to a BLE peripheral
+  advertising this exact name (still gated on the nsn service UUID). Lets
+  several boards running this firmware on one desk stay unambiguous — e.g. a
+  bench board named `Nimbus-BT` vs a production `Nimbus`. On macOS this is the
+  reliable discriminator since CoreBluetooth hides the MAC address.
+
+## [0.1.0] — 2026-07-03
+
+Initial public release, split out of a private monorepo into its own
+standalone package.
+
+### Added
+
+- Broker daemon (`nimbus-notify-broker`) that maintains live session state over a
+  Unix socket and pushes nsn wire-protocol frames to a connected device.
+- `led-report` CLI, invoked from harness hooks to report session events to
+  the broker (fire-and-forget, never blocks the calling harness).
+- Harness adapters for **Claude Code**, **Codex**, and **Mistral Vibe**,
+  including Vibe's session-file watcher and HITL-inference timeout (Vibe has
+  no native session start/stop hook).
+- Two transports: **serial** (USB-CDC, auto-detects Espressif native-USB and
+  common USB-UART bridge chips) and **BLE** (GATT central, with
+  scan/connect/serve/backoff reconnection, MTU negotiation, and full-state
+  resend on every reconnect). Select with `nimbus-notify-broker --transport
+  serial|ble|auto`.
+- Drop-in hook configs for all three harnesses under `hooks/`.
+- Claude Code plugin (`.claude-plugin/plugin.json` + `commands/`) providing
+  `/nsnotify-setup` and `/nsnotify-status`.
+- `docs/protocol.md` — a standalone description of the nsn wire protocol for
+  anyone implementing a compatible device.
+
+[0.1.0]: https://github.com/ristllin/nimbus-notify/releases/tag/v0.1.0

nimbus_notify-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,47 @@
+# Contributing
+
+Issues and pull requests are welcome — bug reports, new harness adapters,
+new transports, or devices you've gotten talking to the broker.
+
+## Development setup
+
+```bash
+git clone https://github.com/ristllin/nimbus-notify.git
+cd nimbus-notify
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+pip install pytest pytest-asyncio
+python3 -m pytest
+```
+
+## Versioning
+
+Every meaningful release: bump `version` in `pyproject.toml`, add a
+`CHANGELOG.md` entry describing it, and tag the commit —
+`git tag -a vX.Y.Z -m "..."` — then push the tag so consumers can pin to a
+specific release instead of tracking `main`.
+
+Semver-for-0.x (pre-1.0): MAJOR stays `0`; MINOR bumps for a new or changed
+public surface (CLI flags, hook payload shape, wire-protocol version,
+breaking or not); PATCH for a fix or internal change with no public-surface
+change. One release can bundle multiple logical commits under one bump —
+just say so in the CHANGELOG entry.
+
+## Adding a harness adapter
+
+Look at `notify/harness/claude.py` (hook-driven) or `notify/harness/vibe.py`
+(hook + background file-watcher, for harnesses without full session
+lifecycle hooks) as templates. An adapter's job is to turn whatever your
+harness gives you (hook stdin JSON, a log file, etc.) into a
+`HarnessEvent` (`notify/harness/base.py`) that `led-report` sends to the
+broker. Add a matching hook config under `hooks/<harness>/` and document the
+wiring in the README.
+
+## Adding a transport
+
+Transports implement the `Transport` protocol in `notify/transport/__init__.py`
+— just `send(frame: bytes) -> bool` and `close() -> None`. See
+`notify/transport/serial_tx.py` for the simplest example and
+`notify/transport/ble_tx.py` for a fuller one with reconnect/backoff. Wire
+a new transport into the `--transport` flag in `notify/broker/server.py`'s
+`_make_transport()`.

nimbus_notify-1.0.0/LICENSE

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

nimbus_notify-1.0.0/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: nimbus-notify
+Version: 1.0.0
+Summary: Host broker that watches your AI coding sessions (Claude Code, Codex, Mistral Vibe) and pushes live status to a physical LED ring / e-ink device over a documented wire protocol
+Project-URL: Homepage, https://github.com/ristllin/nimbus-notify
+Project-URL: Repository, https://github.com/ristllin/nimbus-notify
+Project-URL: Changelog, https://github.com/ristllin/nimbus-notify/blob/main/CHANGELOG.md
+Author: Roy Darnell
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ble,claude-code,codex,hooks,led,mistral-vibe,notifier,serial
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: bleak>=0.22
+Requires-Dist: pyserial>=3.5
+Requires-Dist: watchdog>=4.0
+Description-Content-Type: text/markdown
+
+# nimbus-notify
+
+A Python host broker that watches your AI coding-agent sessions — **Claude
+Code**, **Codex**, and **Mistral Vibe** — via lightweight hooks, and pushes
+their live status (running / waiting for you / needs approval / done /
+errored) to a physical display device over serial (USB-CDC) or Bluetooth LE,
+using a small documented binary protocol ([nsn](docs/protocol.md)).
+
+If you've got several agent sessions going in parallel across different
+terminals and projects, nimbus-notify gives you one glanceable place — an LED
+ring, an e-ink panel, whatever device you point it at — to see which ones
+are still working and which ones are waiting on you.
+
+```
+┌────────────┐   hooks    ┌───────────────┐   nsn wire protocol   ┌──────────┐
+│ Claude Code│ ─────────▶ │               │   (serial or BLE)     │  status  │
+│ Codex      │ ─────────▶ │ nsnotify-     │ ─────────────────────▶│  device  │
+│ Mistral    │ ─────────▶ │  broker       │                       │(your own)│
+│  Vibe      │            │               │                       │          │
+└────────────┘            └───────────────┘                       └──────────┘
+```
+
+## Status
+
+Beta. The core broker, all three harness adapters, and both transports are
+implemented and tested (`python3 -m pytest`). This is a fresh split out of a
+private monorepo into its own package — see [CHANGELOG.md](CHANGELOG.md).
+
+## Compatible devices
+
+nimbus-notify speaks a documented, transport-agnostic wire protocol — see
+[docs/protocol.md](docs/protocol.md). Any device that implements the
+protocol's serial or BLE side can be driven by this broker; nothing here is
+tied to a specific piece of hardware. If you build (or already have) a
+microcontroller project with an LED strip, an e-ink panel, or any other
+status display, point it at this broker.
+
+## Install
+
+Not yet on PyPI — install from a clone:
+
+```bash
+git clone https://github.com/ristllin/nimbus-notify.git
+cd nimbus-notify
+pip install -e .
+```
+
+This installs two commands on your `PATH`:
+
+- `nimbus-notify-broker` — the daemon that maintains session state and talks to
+  your device.
+- `led-report` — the small CLI that harness hooks call to report events
+  into the broker (fire-and-forget; never blocks your agent).
+
+PyPI publishing (`pip install nimbus-notify`) is a planned next step — for now,
+the git-clone path above is the supported install method.
+
+## Quickstart
+
+1. Install the package (above).
+2. Wire up the harness(es) you use — see [Harnesses](#harnesses) below.
+3. Start the broker:
+   ```bash
+   nimbus-notify-broker
+   ```
+4. Start (or resume) an agent session in a wired-up harness. Its status
+   should now be reported to the broker, and forwarded to your device.
+
+If you use Claude Code, the fastest path is the bundled slash commands —
+see [Claude Code plugin](#claude-code-plugin) below.
+
+## Harnesses
+
+nimbus-notify supports three AI coding harnesses today. Each harness reports
+events (session start, a tool running, waiting on your approval, done,
+errored, session end) by calling `led-report <harness> <verb>` from a hook.
+
+### Claude Code
+
+Merge [`hooks/claude/settings.json`](hooks/claude/settings.json)'s `hooks`
+block into your `~/.claude/settings.json`, preserving any hooks you already
+have (append to each event's array rather than replacing it). It wires up
+`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Notification`, `Stop`,
+`StopFailure`, and `SessionEnd`.
+
+### Codex
+
+Merge [`hooks/codex/hooks.json`](hooks/codex/hooks.json) into
+`~/.codex/hooks.json`, then enable hooks and the notify bridge in
+`~/.codex/config.toml`:
+
+```toml
+[features]
+hooks = true
+
+notify = ["led-report", "codex-notify"]
+```
+
+### Mistral Vibe
+
+Vibe has no native session start/stop hook, so the broker also runs a
+background watcher over `~/.vibe/logs/session/` to detect new sessions and
+infer human-in-the-loop waits (if a tool call starts but doesn't finish
+within a timeout, that's treated as "awaiting approval").
+
+Enable experimental hooks in `~/.vibe/config.toml`:
+
+```toml
+enable_experimental_hooks = true
+```
+
+Then merge [`hooks/vibe/hooks.toml`](hooks/vibe/hooks.toml) into
+`~/.vibe/hooks.toml` (requires Vibe v2.15.0+ for `before_tool` /
+`after_tool` / `post_agent_turn`).
+
+### Claude Code plugin
+
+This repo is also a Claude Code plugin (`.claude-plugin/plugin.json`). If
+you install it as a plugin, two slash commands become available:
+
+- `/nsnotify-setup` — installs the Python package, merges the Claude Code
+  hooks automatically, checks whether the broker is running, and prints
+  the manual steps for Codex/Vibe.
+- `/nsnotify-status` — shows current session states without needing to look
+  at the device.
+
+## Transports
+
+Pick a transport with `--transport`:
+
+```bash
+nimbus-notify-broker --transport serial   # default
+nimbus-notify-broker --transport ble
+nimbus-notify-broker --transport auto     # serial if a device is plugged in at
+                                      # startup, else BLE
+```
+
+- **Serial** auto-detects a likely USB-CDC port (Espressif native-USB VID
+  `0x303A`, or common USB-UART bridge chips), or pin one explicitly:
+  `nimbus-notify-broker --transport serial --port /dev/cu.usbmodem101`.
+- **BLE** requires your device to be powered on, flashed with firmware that
+  advertises the nsn BLE service, and in range. Optionally pin a specific
+  device: `nimbus-notify-broker --transport ble --ble-address <address>`
+  (a CoreBluetooth UUID on macOS, a MAC address on Linux). Without
+  `--ble-address`, the broker scans for the nsn service UUID.
+
+Transport selection happens once at startup — there's no live failover
+between serial and BLE mid-session in this version.
+
+### Bonding the BLE link (one time)
+
+Recent Nimbus firmware **secures the BLE link** (bonded + encrypted, LE Secure
+Connections), so a device won't accept frames from an un-bonded computer — this
+stops anyone in radio range from painting your ring. Bonding is **automatic**
+(macOS "Just Works", no code to type) — but there are two things to know:
+
+- **Nimbus does *not* appear in System Settings → Bluetooth.** That list only
+  shows recognized device types (keyboards, mice, audio). A custom BLE
+  peripheral is invisible there by design — don't look for it. Bonding happens
+  on-demand when the broker first touches the device, not by picking it in a
+  list.
+- **Do the first bond with the broker in the foreground.** macOS only completes
+  a bond for a process running in your normal login session — a fully detached
+  process (e.g. `nohup … & disown`) is too detached and the bond silently fails.
+  So the *first* time, just run `nimbus-notify-broker --transport ble` in a normal
+  terminal and leave it up for a few seconds. Once bonded, the bond persists on
+  both the device (flash) and your Mac, and every session after that is
+  transparent — you can then run it backgrounded or as a service (below).
+
+To un-bond: on the device, *Connectivity → Forget paired devices* (or the
+`FORGETBONDS` console command); the Mac side clears on its own next connect.
+
+> The firmware also carries a dormant MITM/passkey mode (it shows a 6-digit code
+> on its e-ink screen). It's off by default because macOS won't surface the
+> passkey-entry dialog for a broker-triggered pairing of a custom peripheral, so
+> that pairing can't complete without a companion app.
+
+## Running persistently
+
+For day-to-day use you'll want the broker running in the background
+whenever you're coding, not started by hand each time.
+
+### macOS (launchd)
+
+Create `~/Library/LaunchAgents/com.nimbus-notify.broker.plist`:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
+  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>com.nimbus-notify.broker</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/bin/env</string>
+    <string>nimbus-notify-broker</string>
+    <string>--transport</string>
+    <string>auto</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>/tmp/nimbus-notify-broker.log</string>
+  <key>StandardErrorPath</key><string>/tmp/nimbus-notify-broker.log</string>
+</dict>
+</plist>
+```
+
+Then:
+
+```bash
+launchctl load ~/Library/LaunchAgents/com.nimbus-notify.broker.plist
+```
+
+### Linux (systemd, user service)
+
+Create `~/.config/systemd/user/nimbus-notify-broker.service`:
+
+```ini
+[Unit]
+Description=nimbus-notify broker
+
+[Service]
+ExecStart=%h/.local/bin/nimbus-notify-broker --transport auto
+Restart=on-failure
+
+[Install]
+WantedBy=default.target
+```
+
+Then:
+
+```bash
+systemctl --user daemon-reload
+systemctl --user enable --now nimbus-notify-broker
+```
+
+Adjust `ExecStart` to wherever `pip install -e .` put the entry point
+(check with `which nimbus-notify-broker`).
+
+## The nsn wire protocol
+
+A short summary — full details in [docs/protocol.md](docs/protocol.md).
+
+```
+[SOF 0xAA] [LEN] [payload: LEN bytes] [CRC8-MAXIM]
+```
+
+The payload starts with magic byte `0x4E`, then a sequence number, then up
+to 16 fixed-size segment records (state, hue, animation, LED span) plus a
+global brightness — enough for a device to render a full status frame from
+a single self-contained packet, no persistent client-side state required.
+The reference encoder/decoder is [`notify/broker/frame.py`](notify/broker/frame.py).
+
+## Repository layout
+
+```
+notify/
+  broker/       frame.py (wire codec), segments.py, server.py, session.py
+  cli/          led_report.py — the hook-facing CLI entry point
+  harness/      base.py + claude.py, codex.py, vibe.py adapters
+  transport/    serial_tx.py, ble_tx.py
+  state.py      shared State/Anim enums + default styling
+tests/          pytest suite for the above
+hooks/          drop-in hook configs per harness
+commands/       Claude Code plugin slash commands
+docs/           protocol.md
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md), including the versioning
+convention used for releases.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Roy Darnell.