nimbus-notify 1.0.0__py3-none-any.whl

nimbus_notify-1.0.0.dist-info/METADATA

@@ -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.

nimbus_notify-1.0.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+notify/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+notify/state.py,sha256=4c_C2nqOlEo4b7dO3KeJxjLIYquX6eWV12RR_Z9oe9A,1894
+notify/broker/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+notify/broker/frame.py,sha256=Ki7_eo0RXEVKpSJ1kmlumu6ydswvnTMVNsb9nFkbyE4,2936
+notify/broker/segments.py,sha256=JYG3qZyz0YyX7Ch1lOYxO4mQaF1sM29sO-6Badnxj78,3632
+notify/broker/server.py,sha256=LgoNAyX5X9OQXJTsUi0xdoQGxBbdhsW885b0SjdIkpI,15605
+notify/broker/session.py,sha256=DWMdAL9miB8AjxaSadnbblIw-38Qh3adSCPkzabs-t0,2530
+notify/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+notify/cli/led_report.py,sha256=iIhC-qN5Rl1y47zH7oZtJynLP-z1J3xDrIb_pOF1diU,3237
+notify/harness/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+notify/harness/base.py,sha256=HdSoevm20mKG3vpBTEfjUcORDd9lA-OCya_0eT9NSZA,578
+notify/harness/claude.py,sha256=HVLwZmNXxZltpURvfoJJDOZ0KM8dA-7LqOrQKmfwgF0,1417
+notify/harness/codex.py,sha256=3TvcLUpDqJ_0oSupQsix2t1rUTqMBAWTOol7xAlOlA0,1261
+notify/harness/vibe.py,sha256=mYGfJwrf1Z33THaQDvLVz1_9mjD26R_0e2EHFVL8stk,6223
+notify/transport/__init__.py,sha256=zy2Lp7gd4K2OCBmo6hv2B0tPgm84EyTXLxlaqWRn0pk,614
+notify/transport/ble_tx.py,sha256=TQqBOasZCivVaCEhZopbQOXD40THe6i-1WM9lmwx_4U,16966
+notify/transport/serial_tx.py,sha256=NnZ0zRZ812vRiHud-a3COBti7HPPF3_mbdTkJnLRvTY,3570
+nimbus_notify-1.0.0.dist-info/METADATA,sha256=c5-hezJrJ4V1SN_B5p4Oc-F03UK3SEM7DVOA3kqppRg,11556
+nimbus_notify-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+nimbus_notify-1.0.0.dist-info/entry_points.txt,sha256=7D2GeGf3dzMiSm0WjyUHH8MoJKhbFJA7eQvRzzQwSoY,107
+nimbus_notify-1.0.0.dist-info/licenses/LICENSE,sha256=5gMUOlQupieheYGvmjavBGr7adTBxAJYaQ8Gj2Po5c8,1068
+nimbus_notify-1.0.0.dist-info/RECORD,,

nimbus_notify-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

nimbus_notify-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+led-report = notify.cli.led_report:main
+nimbus-notify-broker = notify.broker.server:main

nimbus_notify-1.0.0.dist-info/licenses/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.

notify/broker/frame.py

@@ -0,0 +1,108 @@
+"""
+Phase 2 — Wire frame encoder / decoder.
+
+Wire format (bytes on USB-CDC or BLE):
+  [SOF 0xAA] [LEN] [payload: LEN bytes] [CRC8]
+
+Payload:
+  byte 0: MAGIC 0x4E
+  byte 1: sequence number (wraps at 255)
+  byte 2: segment count N
+  byte 3: global brightness (0–255)
+  bytes 4 .. 4+N*4-1: N segment records, 4 bytes each:
+    byte 0: state  (notify.state.State)
+    byte 1: hue    (0–254 HSV hue; 255 = white)
+    byte 2: anim   (notify.state.Anim)
+    byte 3: span   (LED count; 0 = auto-even)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from notify.state import Anim, State, STATE_STYLE
+
+FRAME_SOF   = 0xAA
+FRAME_MAGIC = 0x4E
+MAX_SEGS    = 16
+
+
+@dataclass
+class FrameSegment:
+    state: State
+    hue:   int    # 0–255
+    anim:  Anim
+    span:  int    # 0 = auto
+
+    @classmethod
+    def from_state(cls, state: State, span: int = 0) -> "FrameSegment":
+        hue, anim = STATE_STYLE[state]
+        return cls(state=state, hue=hue, anim=anim, span=span)
+
+
+def _crc8(data: bytes) -> int:
+    """CRC-8/MAXIM (polynomial 0x31, init 0x00, refin/refout True)."""
+    crc = 0
+    for byte in data:
+        crc ^= byte
+        for _ in range(8):
+            crc = (crc >> 1) ^ 0x8C if (crc & 0x01) else (crc >> 1)
+    return crc
+
+
+def encode_frame(segments: list[FrameSegment], brightness: int, seq: int) -> bytes:
+    """Return a complete framed packet ready to write to the transport."""
+    n = min(len(segments), MAX_SEGS)
+    payload = bytes([
+        FRAME_MAGIC,
+        seq & 0xFF,
+        n,
+        brightness & 0xFF,
+    ])
+    for seg in segments[:n]:
+        payload += bytes([
+            int(seg.state) & 0xFF,
+            seg.hue & 0xFF,
+            int(seg.anim) & 0xFF,
+            seg.span & 0xFF,
+        ])
+    crc = _crc8(payload)
+    return bytes([FRAME_SOF, len(payload)]) + payload + bytes([crc])
+
+
+@dataclass
+class DecodedFrame:
+    seq:        int
+    brightness: int
+    segments:   list[FrameSegment]
+
+
+def decode_frame(packet: bytes) -> DecodedFrame | None:
+    """Parse a raw packet (including SOF / LEN / CRC wrapper).  Returns None on error."""
+    if len(packet) < 6:
+        return None
+    if packet[0] != FRAME_SOF:
+        return None
+    length = packet[1]
+    if len(packet) < 2 + length + 1:
+        return None
+    payload = packet[2 : 2 + length]
+    crc     = packet[2 + length]
+    if _crc8(payload) != crc:
+        return None
+    if payload[0] != FRAME_MAGIC:
+        return None
+
+    n          = payload[2]
+    brightness = payload[3]
+    segments: list[FrameSegment] = []
+    for i in range(n):
+        off = 4 + i * 4
+        if off + 4 > len(payload):
+            break
+        segments.append(FrameSegment(
+            state=State(payload[off]),
+            hue=payload[off + 1],
+            anim=Anim(payload[off + 2]),
+            span=payload[off + 3],
+        ))
+    return DecodedFrame(seq=payload[1], brightness=brightness, segments=segments)

notify/broker/segments.py

@@ -0,0 +1,99 @@
+"""
+Phase 2 — Segment allocator.
+
+Rules:
+  - Each live session occupies exactly one segment index (0..MAX_SEGS-1).
+  - Segments are assigned in insertion order (lowest free index wins).
+  - A segment showing AWAITING_APPROVAL or WAITING_INPUT is never evicted to
+    make room for a new session while high-priority slots are full — the new
+    session is assigned the next available index instead.
+  - On free(), the index is returned to the pool immediately.
+  - active_segments() returns SessionRecords ordered by segment index, which
+    determines ring position.
+"""
+from __future__ import annotations
+
+from notify.broker.session import SessionRecord
+from notify.state import State, STATE_PRIORITY
+
+MAX_SEGS = 16
+
+
+class SegmentAllocator:
+    def __init__(self, max_segs: int = MAX_SEGS) -> None:
+        self._max = max_segs
+        self._sessions: dict[str, SessionRecord] = {}  # session_id → record
+        self._index: dict[str, int] = {}               # session_id → segment index
+        self._used: set[int] = set()
+
+    # ------------------------------------------------------------------
+    # Mutation
+    # ------------------------------------------------------------------
+
+    def register(self, record: SessionRecord) -> int:
+        """Assign a segment to a new session.  Returns the segment index, or -1 if full."""
+        if record.session_id in self._index:
+            return self._index[record.session_id]
+
+        idx = self._next_free()
+        if idx < 0:
+            return -1
+
+        self._sessions[record.session_id] = record
+        self._index[record.session_id]    = idx
+        self._used.add(idx)
+        record.segment = idx
+        return idx
+
+    def update(self, record: SessionRecord) -> None:
+        """Update state for an already-registered session."""
+        sid = record.session_id
+        if sid not in self._sessions:
+            self.register(record)
+            return
+        self._sessions[sid].state      = record.state
+        self._sessions[sid].last_event = record.last_event
+
+    def free(self, session_id: str) -> None:
+        """Release the segment held by session_id."""
+        idx = self._index.pop(session_id, None)
+        if idx is not None:
+            self._used.discard(idx)
+        self._sessions.pop(session_id, None)
+
+    def evict_stale(self) -> list[str]:
+        """Remove sessions that have exceeded their TTL.  Returns evicted ids."""
+        stale = [sid for sid, rec in self._sessions.items() if rec.is_stale()]
+        for sid in stale:
+            self.free(sid)
+        return stale
+
+    # ------------------------------------------------------------------
+    # Query
+    # ------------------------------------------------------------------
+
+    def active_segments(self) -> list[SessionRecord]:
+        """Sessions ordered by segment index (ring position)."""
+        return sorted(self._sessions.values(), key=lambda r: self._index[r.session_id])
+
+    def highest_priority_state(self) -> State:
+        """State with the highest priority among all active sessions."""
+        if not self._sessions:
+            return State.Idle
+        return max(
+            (r.state for r in self._sessions.values()),
+            key=lambda s: STATE_PRIORITY[s],
+        )
+
+    def __len__(self) -> int:
+        return len(self._sessions)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _next_free(self) -> int:
+        for i in range(self._max):
+            if i not in self._used:
+                return i
+        return -1