# CLAUDE.md

Guidance for Claude Code when working in this repository.

## What This Is

A Claude Code plugin (no skill — this one is hooks-only) that bridges
Claude Code lifecycle events to a state file the HyprPanel workspaces bar
reads, so each kitty's icon reflects what claude is doing in that
terminal.

## Structure

```
.claude-plugin/plugin.json    # Plugin manifest
.claude-plugin/hooks.json     # Hook event → script mapping
hooks/hyprpanel-state.sh      # The script: PPid walk + state file writes
README.md                     # User-facing docs
```

## Bar Side

This plugin does NOT own the visual — that lives in `~/projects/hyprpanel-dev`
(the patched HyprPanel). The contract between the two is the
`/tmp/hyprpanel-claude/` directory layout (state files, tools counter,
ping sidecar). Changes to the protocol must update both sides.

## Editing Guidelines

- Bump `version` in `plugin.json` for any change Claude Code should pick
  up (it caches by version).
- Hook script path uses `${CLAUDE_PLUGIN_ROOT}` so it works wherever the
  plugin gets installed.
- Keep the script idempotent: hooks may fire concurrently for parallel
  tool calls; the `.tools` counter is flock-protected.
- The PPid-walk address resolution depends on a chain of
  `script → claude → shell → kitty`. Don't break that by spawning the
  script through extra wrappers.

## Why a Plugin (Not Dotfile-Managed)

- Reproducible: install via `claude plugin add`, no manual scp / nixos
  rebuild loop for the script itself.
- Versioned: bumping `plugin.json.version` lets Claude Code re-cache
  cleanly across hosts.
- Decoupled from emmett's NixOS config: the bar visuals are baked in via
  patch (since they're hyprpanel internals), but the hook side is the
  user's claude config and benefits from plugin lifecycle.