# 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