claude-color 0.1.0__tar.gz

claude_color-0.1.0/LICENSE

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

claude_color-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: claude-color
+Version: 0.1.0
+Summary: Drive any wired VIA-compatible RGB keyboard from Claude Code status
+Author: Edocksil
+License: MIT
+Project-URL: Homepage, https://github.com/Edocksil/claude-color
+Project-URL: Repository, https://github.com/Edocksil/claude-color
+Project-URL: Issues, https://github.com/Edocksil/claude-color/issues
+Keywords: claude-code,qmk,via,hid,rgb,keyboard,hooks,status
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Environment :: Console
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hidapi>=0.14
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Dynamic: license-file
+
+# claude-color
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+![Platform: Windows](https://img.shields.io/badge/platform-Windows-blue.svg)
+
+**[Live docs & demo → edocksil.github.io/claude-color](https://edocksil.github.io/claude-color/)**
+
+Drive a wired **VIA-compatible keyboard's** RGB from Claude Code status — see at a glance
+whether Claude is working, waiting for you, or idle, without looking at the terminal.
+
+- **working** → blue-purple
+- **waiting for you** (permission / input) → amber
+- **idle** (turn done, session alive) → deep green
+- **Claude Code exits / no session running** → your normal lighting is restored
+
+## Why claude-color
+
+Built to be **correct under real conditions**, not just a demo:
+
+- **Multi-session aware** — one keyboard, many Claude Code sessions, resolved by
+  priority (`waiting` > `working` > `idle`).
+- **Survives crashes & sleep** — sessions are tracked by their Claude process;
+  dead ones are pruned, and a boot/logon/unlock reconcile restores your lighting
+  when no session is running.
+- **Accurate status** — distinguishes a real permission prompt (amber) from a
+  finished-but-idle session (green) via Claude Code's `notification_type`.
+- **Restores your lighting** — captures your real keyboard color and puts it back,
+  with a guard against capturing its own status colors.
+- **Windows-first**, keyboard-generic (any wired VIA RGB keyboard), 85+ tests.
+
+## Requirements
+
+- **Windows 11**, Python 3.11+ — installed and run via [uv](https://docs.astral.sh/uv/)
+  (no system Python needed).
+- **Any wired keyboard exposing a VIA raw-HID interface with an RGB matrix**,
+  connected by **USB cable**. VIA support is most commonly provided by QMK
+  firmware with VIA enabled, but only the VIA protocol is required — not QMK
+  itself. Developed and validated on the **Keychron Q6 Max**. **Wireless is not
+  supported** (wired only). See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+- Optional but recommended: the [`qmk_hid`](https://github.com/FrameworkComputer/qmk_hid)
+  binary on your PATH (primary backend). Without it, the built-in Python `hidapi`
+  backend is used.
+
+## Install
+
+```powershell
+uv run claude-color doctor        # confirm the keyboard is detected
+uv run claude-color test          # cycle working/waiting/idle, then restore
+uv run claude-color install       # add hooks to %USERPROFILE%\.claude\settings.json
+```
+
+To make `claude-color` a global command (so Claude Code can invoke the hooks from any
+terminal), install it as a uv tool — `--editable` keeps it tracking this repo:
+
+```powershell
+uv tool uninstall kbstatus     # remove the old command (if previously installed)
+uv tool install --editable .   # exposes `claude-color` on PATH (~\.local\bin)
+claude-color install           # wire hooks (migrates any old kbstatus wiring)
+```
+
+Ensure the uv tool bin dir is on PATH so Claude Code and the scheduled task can
+invoke `claude-color`.
+
+## Demo
+
+Run the color cycle any time to see (or show off) all three statuses. It cycles
+**working → waiting → idle** and then restores your current lighting:
+
+```powershell
+claude-color test                 # ~2s per color (quick check)
+claude-color test --dwell 30      # hold each color 30s (slow demo)
+```
+
+## Configure
+
+Edit `%LOCALAPPDATA%\claude-color\config.toml`:
+
+- `backend` — `auto` (default), `qmk_hid`, or `hidapi`
+- `solid_effect_index` — the VIA "solid color" effect index for your keymap. If
+  `claude-color test` shows an animation instead of a solid color, change this and
+  rerun `claude-color test`.
+- `vid` / `pid` — hex, only needed if multiple HID devices match. Find yours with
+  `claude-color doctor` or `qmk_hid -l`.
+- `[colors]` — H/S/V (0–255) per state
+- `staleness_minutes` — a stuck session is forgotten after this (default 120)
+
+## How it works
+
+```mermaid
+flowchart LR
+    CC["Claude Code hooks"] -->|"SessionStart · UserPromptSubmit · Notification · Stop · SessionEnd"| K["claude-color hook"]
+    K --> S["state.json<br/>(per session, by PID)"]
+    S -->|"winner: waiting &gt; working &gt; idle"| KB["keyboard RGB<br/>(VIA raw-HID)"]
+    R["claude-color reconcile<br/>(logon / unlock)"] --> S
+```
+
+Claude Code fires hooks (`SessionStart`, `UserPromptSubmit`, `Notification`,
+`Stop`, `SessionEnd`). Each runs `claude-color hook`, which updates a per-session
+state file (`%LOCALAPPDATA%\claude-color\state.json`) and pushes the highest-priority
+color (`waiting` > `working` > `idle`) across all live sessions. Sessions are
+tracked by their Claude process id; dead ones are pruned, and a scheduled
+`claude-color reconcile` (logon/unlock) restores your lighting when no Claude is
+running. When the last session ends, the lighting captured at first
+`SessionStart` is restored.
+
+## Troubleshooting
+
+- **No color changes:** run `claude-color doctor`. If `available: False`, check the USB
+  cable (wireless is not supported) and try `backend = "hidapi"` or set `vid`/`pid`.
+- **Animation instead of solid color:** fix `solid_effect_index`.
+- **Colors never restore:** baseline capture may be unsupported on your firmware
+  via the active backend; try `backend = "hidapi"`. Logs are in
+  `%LOCALAPPDATA%\claude-color\claude-color.log`.
+- **Uninstall:** `claude-color uninstall`.
+
+## License
+
+[MIT](LICENSE) — © 2026 Edocksil.

claude_color-0.1.0/README.md

@@ -0,0 +1,119 @@
+# claude-color
+
+![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)
+![Platform: Windows](https://img.shields.io/badge/platform-Windows-blue.svg)
+
+**[Live docs & demo → edocksil.github.io/claude-color](https://edocksil.github.io/claude-color/)**
+
+Drive a wired **VIA-compatible keyboard's** RGB from Claude Code status — see at a glance
+whether Claude is working, waiting for you, or idle, without looking at the terminal.
+
+- **working** → blue-purple
+- **waiting for you** (permission / input) → amber
+- **idle** (turn done, session alive) → deep green
+- **Claude Code exits / no session running** → your normal lighting is restored
+
+## Why claude-color
+
+Built to be **correct under real conditions**, not just a demo:
+
+- **Multi-session aware** — one keyboard, many Claude Code sessions, resolved by
+  priority (`waiting` > `working` > `idle`).
+- **Survives crashes & sleep** — sessions are tracked by their Claude process;
+  dead ones are pruned, and a boot/logon/unlock reconcile restores your lighting
+  when no session is running.
+- **Accurate status** — distinguishes a real permission prompt (amber) from a
+  finished-but-idle session (green) via Claude Code's `notification_type`.
+- **Restores your lighting** — captures your real keyboard color and puts it back,
+  with a guard against capturing its own status colors.
+- **Windows-first**, keyboard-generic (any wired VIA RGB keyboard), 85+ tests.
+
+## Requirements
+
+- **Windows 11**, Python 3.11+ — installed and run via [uv](https://docs.astral.sh/uv/)
+  (no system Python needed).
+- **Any wired keyboard exposing a VIA raw-HID interface with an RGB matrix**,
+  connected by **USB cable**. VIA support is most commonly provided by QMK
+  firmware with VIA enabled, but only the VIA protocol is required — not QMK
+  itself. Developed and validated on the **Keychron Q6 Max**. **Wireless is not
+  supported** (wired only). See [docs/COMPATIBILITY.md](docs/COMPATIBILITY.md).
+- Optional but recommended: the [`qmk_hid`](https://github.com/FrameworkComputer/qmk_hid)
+  binary on your PATH (primary backend). Without it, the built-in Python `hidapi`
+  backend is used.
+
+## Install
+
+```powershell
+uv run claude-color doctor        # confirm the keyboard is detected
+uv run claude-color test          # cycle working/waiting/idle, then restore
+uv run claude-color install       # add hooks to %USERPROFILE%\.claude\settings.json
+```
+
+To make `claude-color` a global command (so Claude Code can invoke the hooks from any
+terminal), install it as a uv tool — `--editable` keeps it tracking this repo:
+
+```powershell
+uv tool uninstall kbstatus     # remove the old command (if previously installed)
+uv tool install --editable .   # exposes `claude-color` on PATH (~\.local\bin)
+claude-color install           # wire hooks (migrates any old kbstatus wiring)
+```
+
+Ensure the uv tool bin dir is on PATH so Claude Code and the scheduled task can
+invoke `claude-color`.
+
+## Demo
+
+Run the color cycle any time to see (or show off) all three statuses. It cycles
+**working → waiting → idle** and then restores your current lighting:
+
+```powershell
+claude-color test                 # ~2s per color (quick check)
+claude-color test --dwell 30      # hold each color 30s (slow demo)
+```
+
+## Configure
+
+Edit `%LOCALAPPDATA%\claude-color\config.toml`:
+
+- `backend` — `auto` (default), `qmk_hid`, or `hidapi`
+- `solid_effect_index` — the VIA "solid color" effect index for your keymap. If
+  `claude-color test` shows an animation instead of a solid color, change this and
+  rerun `claude-color test`.
+- `vid` / `pid` — hex, only needed if multiple HID devices match. Find yours with
+  `claude-color doctor` or `qmk_hid -l`.
+- `[colors]` — H/S/V (0–255) per state
+- `staleness_minutes` — a stuck session is forgotten after this (default 120)
+
+## How it works
+
+```mermaid
+flowchart LR
+    CC["Claude Code hooks"] -->|"SessionStart · UserPromptSubmit · Notification · Stop · SessionEnd"| K["claude-color hook"]
+    K --> S["state.json<br/>(per session, by PID)"]
+    S -->|"winner: waiting &gt; working &gt; idle"| KB["keyboard RGB<br/>(VIA raw-HID)"]
+    R["claude-color reconcile<br/>(logon / unlock)"] --> S
+```
+
+Claude Code fires hooks (`SessionStart`, `UserPromptSubmit`, `Notification`,
+`Stop`, `SessionEnd`). Each runs `claude-color hook`, which updates a per-session
+state file (`%LOCALAPPDATA%\claude-color\state.json`) and pushes the highest-priority
+color (`waiting` > `working` > `idle`) across all live sessions. Sessions are
+tracked by their Claude process id; dead ones are pruned, and a scheduled
+`claude-color reconcile` (logon/unlock) restores your lighting when no Claude is
+running. When the last session ends, the lighting captured at first
+`SessionStart` is restored.
+
+## Troubleshooting
+
+- **No color changes:** run `claude-color doctor`. If `available: False`, check the USB
+  cable (wireless is not supported) and try `backend = "hidapi"` or set `vid`/`pid`.
+- **Animation instead of solid color:** fix `solid_effect_index`.
+- **Colors never restore:** baseline capture may be unsupported on your firmware
+  via the active backend; try `backend = "hidapi"`. Logs are in
+  `%LOCALAPPDATA%\claude-color\claude-color.log`.
+- **Uninstall:** `claude-color uninstall`.
+
+## License
+
+[MIT](LICENSE) — © 2026 Edocksil.

claude_color-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "claude-color"
+version = "0.1.0"
+description = "Drive any wired VIA-compatible RGB keyboard from Claude Code status"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Edocksil" }]
+keywords = ["claude-code", "qmk", "via", "hid", "rgb", "keyboard", "hooks", "status"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Environment :: Console",
+    "Operating System :: Microsoft :: Windows",
+    "Topic :: Utilities",
+]
+dependencies = ["hidapi>=0.14"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8"]
+
+[project.scripts]
+claude-color = "claude_color.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Edocksil/claude-color"
+Repository = "https://github.com/Edocksil/claude-color"
+Issues = "https://github.com/Edocksil/claude-color/issues"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

claude_color-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

claude_color-0.1.0/src/claude_color/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

claude_color-0.1.0/src/claude_color/__main__.py

@@ -0,0 +1,4 @@
+from claude_color.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

claude_color-0.1.0/src/claude_color/cli.py

@@ -0,0 +1,169 @@
+import argparse
+import json
+import sys
+import time
+
+from claude_color import config, events, install, paths, procinfo, statestore
+from claude_color.keyboard.factory import get_backend
+from claude_color.keyboard.hidapi import list_via_devices
+from claude_color.lock import DirLock
+from claude_color.logging_setup import get_logger
+
+log = get_logger()
+
+
+def now() -> float:
+    return time.time()
+
+
+def cmd_hook() -> int:
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+        event_name = payload.get("hook_event_name")
+        session_id = payload.get("session_id") or "default"
+        if not event_name:
+            return 0
+        cfg = config.load_config()
+        keyboard = get_backend(cfg)
+        pid = procinfo.session_pid()
+        live = procinfo.live_claude_pids()
+        boot = procinfo.boot_time()
+        with DirLock(paths.lock_path()) as acquired:
+            if not acquired:
+                return 0
+            state = statestore.load_state(paths.state_path())
+            before = json.dumps(state, sort_keys=True)
+            events.handle_event(
+                event_name, session_id, now(), cfg, state, keyboard,
+                notification_type=payload.get("notification_type"),
+                pid=pid, live_pids=live, boot_time=boot,
+            )
+            after = json.dumps(state, sort_keys=True)
+            if before != after:  # write-on-change
+                statestore.save_state(paths.state_path(), state)
+    except Exception as exc:
+        log.warning("hook error: %s", exc, exc_info=True)
+    return 0
+
+
+def cmd_reconcile() -> int:
+    """Prune sessions whose Claude process has exited and restore the user's
+    lighting if none remain. Meant to run on boot/unlock (scheduled task) so the
+    keyboard recovers after ungraceful exits that never fired SessionEnd."""
+    try:
+        cfg = config.load_config()
+        keyboard = get_backend(cfg)
+        live = procinfo.live_claude_pids()
+        boot = procinfo.boot_time()
+        with DirLock(paths.lock_path()) as acquired:
+            if not acquired:
+                return 0
+            state = statestore.load_state(paths.state_path())
+            before = json.dumps(state, sort_keys=True)
+            events.reconcile(cfg, state, keyboard, live, now(), boot)
+            after = json.dumps(state, sort_keys=True)
+            if before != after:
+                statestore.save_state(paths.state_path(), state)
+    except Exception as exc:
+        log.warning("reconcile error: %s", exc, exc_info=True)
+    return 0
+
+
+def _device_label(manufacturer: str, product: str) -> str:
+    """Human-readable device name, avoiding a doubled brand when the product
+    string already starts with the manufacturer (e.g. "Keychron" + "Keychron
+    Q6 Max" -> "Keychron Q6 Max")."""
+    m, p = (manufacturer or "").strip(), (product or "").strip()
+    if not m:
+        return p
+    if not p:
+        return m
+    if p.lower().startswith(m.lower()):
+        return p
+    return f"{m} {p}"
+
+
+def cmd_doctor() -> int:
+    cfg = config.load_config()
+    keyboard = get_backend(cfg)
+    print(f"backend: {type(keyboard).__name__}")
+    print(f"available: {keyboard.available()}")
+    current = keyboard.get_hsv()
+    print(f"current lighting (baseline capture): {current}")
+    print(f"solid_effect_index (config): {cfg.get('solid_effect_index')}")
+    devices = list_via_devices()
+    if devices:
+        print("Detected VIA devices (usage page 0xFF60):")
+        for d in devices:
+            label = _device_label(d["manufacturer"], d["product"])
+            print(f"  vid={d['vid']} pid={d['pid']}  {label}".rstrip())
+        print("If the wrong device is picked, set vid/pid in config.toml.")
+    else:
+        print("No VIA devices detected (check the USB cable; wireless is not supported).")
+    print("If colors look wrong, adjust solid_effect_index in config.toml and rerun `claude-color test`.")
+    return 0
+
+
+def cmd_test(dwell: float = 2.0) -> int:
+    """Demo/test: cycle working -> waiting -> idle on the keyboard, holding each
+    color `dwell` seconds, then restore the current lighting as the baseline."""
+    cfg = config.load_config()
+    keyboard = get_backend(cfg)
+    effect = cfg.get("solid_effect_index", 1)
+    baseline = keyboard.get_hsv()
+    for name in ("working", "waiting", "idle"):
+        h, s, v = cfg["colors"][name]
+        print(f"{name:>8}: hsv=({h},{s},{v})  (holding {dwell}s)", flush=True)
+        keyboard.set_hsv(effect, h, s, v)
+        time.sleep(dwell)
+    if baseline is not None:
+        print(f"restoring baseline: {baseline}", flush=True)
+        keyboard.set_hsv(baseline.effect, baseline.hue, baseline.sat, baseline.val)
+    else:
+        print("baseline unavailable (backend can't read current lighting) - left on idle", flush=True)
+    return 0
+
+
+def cmd_status() -> int:
+    state = statestore.load_state(paths.state_path())
+    print(json.dumps(state, indent=2))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="claude-color")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("hook", help="hook entrypoint (reads JSON on stdin)")
+    sub.add_parser("install", help="add hooks to Claude Code settings.json")
+    sub.add_parser("uninstall", help="remove hooks from Claude Code settings.json")
+    sub.add_parser("doctor", help="detect keyboard and report status")
+    test_parser = sub.add_parser(
+        "test", help="demo: cycle status colors on the keyboard, then restore"
+    )
+    test_parser.add_argument(
+        "--dwell", type=float, default=2.0,
+        help="seconds to hold each color (default: 2.0; e.g. 30 for a slow demo)",
+    )
+    sub.add_parser("status", help="print current state.json")
+    sub.add_parser(
+        "reconcile",
+        help="prune dead sessions and restore lighting if no Claude is running",
+    )
+
+    args = parser.parse_args(argv)
+    if args.command == "hook":
+        return cmd_hook()
+    if args.command == "reconcile":
+        return cmd_reconcile()
+    if args.command == "install":
+        return install.cmd_install()
+    if args.command == "uninstall":
+        return install.cmd_uninstall()
+    if args.command == "doctor":
+        return cmd_doctor()
+    if args.command == "test":
+        return cmd_test(args.dwell)
+    if args.command == "status":
+        return cmd_status()
+    return 1

claude_color-0.1.0/src/claude_color/config.py

@@ -0,0 +1,59 @@
+import copy
+import tomllib
+
+from claude_color import paths
+
+DEFAULTS: dict = {
+    "backend": "auto",           # auto | qmk_hid | hidapi
+    "qmk_hid_path": "qmk_hid",   # binary name or full path
+    "vid": "",                    # hex string, e.g. "3434"; "" = no filter
+    "pid": "",                    # hex string; "" = no filter
+    "solid_effect_index": 1,      # VIA RGB-matrix "solid color" effect index
+    "staleness_minutes": 120,
+    "colors": {
+        "working": [180, 255, 200],
+        "waiting": [30, 255, 220],
+        "idle": [90, 255, 120],
+    },
+}
+
+_TEMPLATE = """\
+# claude-color configuration
+backend = "auto"          # auto | qmk_hid | hidapi
+qmk_hid_path = "qmk_hid"  # binary name on PATH, or a full path
+vid = ""                   # hex, e.g. "3434"; empty = no device filter
+pid = ""                   # hex; empty = no device filter
+solid_effect_index = 1     # VIA RGB-matrix solid-color effect index (confirm via `claude-color doctor`)
+staleness_minutes = 120
+
+[colors]                   # H, S, V on QMK 0-255 scale
+working = [180, 255, 200]
+waiting = [30, 255, 220]
+idle = [90, 255, 120]
+"""
+
+
+def _merge(base: dict, over: dict) -> dict:
+    out = copy.deepcopy(base)
+    for k, v in over.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _merge(out[k], v)
+        else:
+            out[k] = v
+    return out
+
+
+def load_config() -> dict:
+    path = paths.config_path()
+    if not path.exists():
+        try:
+            path.write_text(_TEMPLATE, encoding="utf-8")
+        except Exception:
+            return copy.deepcopy(DEFAULTS)
+        return copy.deepcopy(DEFAULTS)
+    try:
+        with path.open("rb") as fh:
+            loaded = tomllib.load(fh)
+        return _merge(DEFAULTS, loaded)
+    except Exception:
+        return copy.deepcopy(DEFAULTS)