initial: hyprpanel-state plugin

Hooks-only Claude Code plugin that surfaces per-window claude state
in the patched HyprPanel workspaces bar. Wires UserPromptSubmit /
PreToolUse / PostToolUse / Notification / Stop / SessionEnd to a
shell script that walks the parent-PID chain to find the kitty
client whose claude this script lives in, then writes a state token
to /tmp/hyprpanel-claude/<address>.

Bar visuals are owned separately by the workspaces patch in
projects/hyprpanel-dev. The contract between the two is the
/tmp/hyprpanel-claude/ directory layout (state file, .tools
counter, .ping sidecar for blink-decay animations).

README.md

@@ -0,0 +1,62 @@
+# hyprpanel-state
+
+Claude Code plugin that surfaces per-window claude state in the HyprPanel
+workspaces bar.
+
+## What it does
+
+Wires Claude Code hooks (UserPromptSubmit / PreToolUse / PostToolUse /
+Notification / Stop / SessionEnd) to a shell script that walks the parent
+PID chain from itself up through claude → shell → kitty until it finds a
+PID owned by a Hyprland kitty client, then writes a state token to
+`/tmp/hyprpanel-claude/<address>`. The patched HyprPanel bar reads those
+tokens and tints each kitty's app icon by what claude is doing.
+
+| State       | Color (in bar) | Pip indicator | Triggered by                                      |
+| ----------- | -------------- | ------------- | ------------------------------------------------- |
+| `active`    | blue           | `●`           | `UserPromptSubmit` / `PreToolUse` / `PostToolUse` |
+| `waiting`   | orange         | `●`           | `Notification` (suppressed when state is done/scheduled) |
+| `done`      | green          | `✔`           | `Stop` (no `ScheduleWakeup` in last assistant turn) |
+| `scheduled` | cyan           | `⧗`           | `Stop` (last turn used `ScheduleWakeup` / `CronCreate`) |
+| (cleared)   | default        | —             | `SessionEnd`                                      |
+
+A blink-decay opacity animation fires on (re-)assignment of waiting,
+scheduled, done — and on the agent-idle "remember me" Notification while
+already done. Sticky-done means the green check survives idle pings.
+
+## Sidecar files
+
+- `/tmp/hyprpanel-claude/<addr>` — current state token
+- `/tmp/hyprpanel-claude/.<addr>.tools` — tool-in-flight counter
+  (incremented on PreToolUse, decremented on PostToolUse, flock-protected
+  for parallel tool fan-outs)
+- `/tmp/hyprpanel-claude/.<addr>.ping` — touch-only sidecar; mtime advance
+  triggers the bar's blink animation
+
+## Bar side
+
+The visuals live in HyprPanel and are not owned by this plugin. Install /
+patch HyprPanel separately — see `~/projects/hyprpanel-dev/PROMPT.md` for
+the workspaces module changes that read these state files.
+
+## Dependencies
+
+- `hyprctl` (Hyprland)
+- `jq`
+- `flock`
+
+All standard on a NixOS desktop.
+
+## Install
+
+```bash
+claude plugin add https://claude-plugins.oleks.space/plugins/hyprpanel-state.git
+```
+
+Once enabled, the hook chain wires itself up — no `~/.claude/settings.json`
+edits required. Claude sessions started after the install will fire hooks
+into the script; pre-existing sessions need to restart to pick them up.
+
+## License
+
+MIT