prompt-chime CLAUDE.md

CLAUDE.md

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

Project Overview

prompt-chime is a cross-platform notification toolkit for AI coding assistants. It plays sounds and shows toast notifications when prompts complete. It's a Claude Code plugin that registers a Stop hook.

Commands

# Run E2E tests (requires python3)
bash scripts/test_e2e.sh

# Test a notification manually
bash scripts/notify.sh --event stop --title "Test" --body "Hello"

# Management CLI
bash scripts/manage.sh status
bash scripts/manage.sh test
bash scripts/manage.sh help

There is no build step. No package manager. No linter configured.

Architecture

The codebase is pure shell scripts (bash + PowerShell) with inline Python for JSON config manipulation. No external dependencies.

Entry Points

• hooks/hooks.json — Claude Code Stop hook definition; triggers scripts/notify.sh async on every assistant stop
• install.sh — Copies scripts/ to ~/.claude/notifications/ and registers the Stop hook in ~/.claude/settings.json
• .claude-plugin/plugin.json — Plugin manifest for marketplace-style installation

Core Scripts (all in scripts/)

• notify.sh — Main notification dispatcher. Parses args (--event, --project, --title, --body), reads config.json via embedded Python, resolves sound file, detects OS, delegates to platform script. Falls back to pure-bash grep if python3 is unavailable.
• manage.sh — CLI for managing config (volume, quiet hours, toast, profiles, project overrides, sound selection). All config mutations go through the pyconf() helper which embeds Python code strings — user input must only pass through sys.argv, never interpolated into the Python code string.
• platforms/windows.ps1 — Windows: Win32 MCI (mciSendString via P/Invoke) for audio (WAV+MP3), WinRT ToastNotificationManager for toasts (BalloonTip fallback). Toast fires first for instant feedback, then sound plays synchronously.
• platforms/macos.sh — macOS: afplay for audio, osascript for toasts
• platforms/linux.sh — Linux: paplay/pw-play/aplay for audio, notify-send for toasts
• config.json — Default configuration (gets copied to install dir; the installed copy is what's read at runtime)
• test_e2e.sh — E2E test suite (9 test groups: structure, sounds, config, OS detection, CLI, profiles, project overrides, security, live notification)
• generate_meme_sounds.py — Synthesizes chiptune meme notification sounds (Mario 1-Up, Zelda secret, etc.) as WAV files into sounds/custom/. Run with python3 scripts/generate_meme_sounds.py. Output is gitignored.