CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Claude Code plugin that sends cross-platform desktop notifications (Windows/macOS/Linux) via Claude Code hooks. Installed as a Claude Code plugin via the marketplace. No build system, no npm, no tests — pure shell/PowerShell scripts.

Architecture

Two parallel notification paths share identical logic in different languages:

hooks/hooks.json          ← Hook definitions (SessionStart, Stop, Notification, StopFailure)
    │
    ├─ Windows path:
    │   run-hook.cmd → notify.ps1 (BurntToast toast notifications)
    │   setup.cmd    → setup.ps1  (SessionStart: installs BurntToast, generates icon)
    │
    └─ macOS/Linux path:
        run-hook.sh  → notify.sh   (osascript / terminal-notifier / notify-send)
        setup.sh                    (SessionStart: checks tools, generates icon)

The run-hook.sh also handles Windows (MSYS/MINGW/Cygwin) by delegating to notify.ps1.

Both notify.ps1 and notify.sh share the same flow: read JSON from stdin → detect project name (git) + terminal identity → map type (info/success/warning/error) to title/sound → send platform notification.

Standalone installers (install.ps1 / install.sh) exist as an alternative to the plugin marketplace — they manually register hooks into ~/.claude/settings.json. The plugin marketplace uses hooks/hooks.json auto-loading instead.

Key Conventions

• Icon file: ~/.claude/notify-icon.png (64x64 PNG, auto-generated if missing using .NET System.Drawing on Windows, Python on Unix)
• Hook types: info (Stop), warning (Notification+permission_prompt), error (StopFailure)
• JSON parsing on Unix: tries jq first, falls back to python3/python, then crude sed
• All scripts handle missing dependencies gracefully with fallbacks
• PowerShell scripts require #Requires -Version 5.1