dding-dong
CLAUDE.md2 starsChanged 9 months agoMITView on GitHub
Claude Code notification plugin. Plays sounds and sends OS notifications on task completion, errors, and input requests. Zero npm dependencies — uses only Node.js built-in modules.
- Reads credentials
- Installs packages
In this repository12 other files it gives its agents.
- claude-md-optimizerSkill
- wrap-upSkill
- dd-configSkill
- dd-doctorSkill
- dd-feedbackSkill
- dd-helpSkill
- dd-pack-createSkill
- dd-setupSkill
- dd-soundsSkill
- dd-testSkill
- dd-tts-packSkill
- dd-uninstallSkill
The file
We split this CLAUDE.md into the rules it gives an agent
9 rules. About 0 are common, 1 is distinctive, and 8 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
8
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 47
ESM only: All scripts use .mjs extension with import/export syntax.
- Very specific: line 48
No npm dependencies: Only Node.js built-in modules (node:fs, node:path, node:child_process, node:os, node:url).
- Very specific: line 54
Only the stop hook requires {} response (Claude awaits it).
- Very specific: line 75
NEVER generate TTS files in parallel: Always run generate-tts.py sequentially, one event at a time.
- Very specific: line 89
Tailwind v4 opacity: Use integer presets (text-hobak/7), never decimal brackets (text-hobak/[0.07]).
- Very specific: line 91
Post-change verification required: After any website code change, always run cd website && pnpm build and cd website && pnpm lint to verify …
- Very specific: line 102
Commit order: feature/fix commit first → version bump as a separate chore: commit
- Distinctive: line 109
No automated test suite exists yet.
- Very specific: line 110
Test runner: node:test (maintains zero-dependency policy)
≈ “Common” is an estimate: at least 1 in 5 of the 27,641 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
dding-dong
Claude Code notification plugin. Plays sounds and sends OS notifications on task completion, errors, and input requests. Zero npm dependencies — uses only Node.js built-in modules.
Development Commands
# Test notifications (cycles through all event types)
node scripts/notify.mjs test
# Regenerate default sound pack WAV files
node scripts/generate-sounds.mjs
# Detect platform, audio player, and notifier
node scripts/setup-wizard.mjs detect
# Validate config files (JSON parsing, required keys, sound pack existence)
node scripts/setup-wizard.mjs validate
# Sound pack management (discover, validate, create, clone, apply)
node scripts/pack-wizard.mjs discover
# Version sync (plugin.json → marketplace.json)
node scripts/sync-version.mjs sync
node scripts/sync-version.mjs verify
node scripts/sync-version.mjs bump patch # or minor, major
# Release (creates git tag + pushes → GitHub Actions creates release)
node scripts/release.mjs # Create git tag and push
node scripts/release.mjs --dry-run # Preview without creating tag
# Website (pnpm required — do NOT use npm/yarn)
cd website && pnpm install # Install dependencies
cd website && pnpm dev # Dev server (auto-copies sound files)
cd website && pnpm build # Production buildDesign Rules
- Simplicity First: Make every change as simple as possible. Impact minimal code.
- Root cause fixes: Find root causes. No temporary fixes. Senior developer standards.
- Minimal impact: Changes should only touch what's necessary. Avoid introducing bugs.
- Stop hook MUST respond:
stop.mjsmust write{}(empty JSON object) to stdout. Missing this halts Claude execution. - Always exit(0) on error: Notification failure must never block Claude. All hook catch blocks call
process.exit(0). - detached + unref: Audio processes use
spawn(..., { detached: true, stdio: 'ignore' }).unref()to complete within the 5-second hook timeout. - ESM only: All scripts use
.mjsextension withimport/exportsyntax. - No npm dependencies: Only Node.js built-in modules (
node:fs,node:path,node:child_process,node:os,node:url).
Gotchas & Landmines
Hook Timing
- hooks.json 5s timeout → internal safety timer 4s → stdin read 2s → only ~2s left for notify()
- Only the stop hook requires
{}response (Claude awaits it). All other hooks need no response uncaughtException/unhandledRejectionhandlers guarantee response thenexit(0)— last-resort safety net
Config
- 5-stage merge (later wins): Default ← Global ← Project ← Local ← env vars
_meta: extracted before deepMerge, re-attached after. Global-only. Cannot be polluted by project confignullin deepMerge = key deletion.{ "sound": null }→ removes the sound key entirely. To disable, use{ "sound": { "enabled": false } }- Project/Local scopes store diff-only overrides (not full snapshots)
saveConfigruns round-tripJSON.parsevalidation. On failure, auto-restores from backup- Backups: max 3 per config file, oldest auto-deleted
Platform
- WSL detection: checks
/proc/versionfor "microsoft" (case-insensitive).process.platformreturns"linux"even on WSL - Linux audio priority:
pw-play>paplay>ffplay>mpv>aplay - WSL notification priority:
wsl-notify-send> WinRT PowerShell Toast > terminal bell
Sound Packs
- Resolution order: Project (
.dding-dong/packs/) → User (~/.config/dding-dong/packs/) → Built-in (sounds/) - Rotation:
"random"= random pick fromfiles[]."sequential"or unset = alwaysfiles[0](no cycling)
TTS Generation
- NEVER generate TTS files in parallel. Always run
generate-tts.pysequentially, one event at a time. Parallel GPU inference causes resource conflicts and unpredictable output quality
Cooldown
- Global (not per-event). Single
lastNotifiedAttimestamp. Asession.startwithin 3s oftask.completeis suppressed
Events
task.error: defined in config/messages but has no triggering hook. Only testable via CLI test mode. Reserved for future Claude Code error hook support
Website
- pnpm only:
website/uses pnpm. Do NOT usenpm installoryarn— breakspnpm-lock.yaml - Tailwind v4 — no config file:
tailwind.config.jsdoes not exist. Theme is defined insrc/styles/global.cssvia@themeblock - Sound copy dependency:
pnpm dev/buildrunscopy-sounds.mjswhich requires../sounds/to exist.public/sounds/is gitignored and ephemeral - Base URL
/dding-dong/: For GitHub Pages. All internal links must uselocalePath()orimport.meta.env.BASE_URL. Missing base URL → works locally, 404 on deploy - Korean color names: Theme variables in
global.cssuse Korean names (hanji, meok, onggi, etc.). This is intentional — do not rename to English - Tailwind v4 opacity: Use integer presets (
text-hobak/7), never decimal brackets (text-hobak/[0.07]). Arbitrary values are only allowed when no preset exists (e.g.,calc()or custom grids) - i18n manual routing: Pages at
pages/ko/index.astromust be created manually. Astro i18n does not auto-generate locale pages - Post-change verification required: After any website code change, always run
cd website && pnpm buildandcd website && pnpm lintto verify no errors before considering the task complete
SKILL.md Conventions
- Description format:
"<English description>. <Korean summary>. Use when the user says '<triggers>'." disable-model-invocation: true→ mechanical skill (run script + report result). Omit → needs model reasoningcontext: fork→ only used bydd-doctor. For independent diagnostic analysis requiring a subagent
Version Management
plugin.jsonis the single source of truth. semver:feat:→ minor,fix:→ patch- Commit order: feature/fix commit first → version bump as a separate
chore:commit node scripts/sync-version.mjs bump patch|minor|majornode scripts/sync-version.mjs verify(exits 1 on mismatch)- Release flow: version bump commit →
node scripts/release.mjs→ GitHub Actions creates release
Testing
No automated test suite exists yet. When adding tests:
- Test runner:
node:test(maintains zero-dependency policy) - Priority:
config.mjs(5-stage merge),platform.mjs(detection),notify.mjs(dispatch flow) - Hook tests: stop.mjs must always output
{}, all hooks must exit(0) on error - Sound pack tests: manifest validation, resolution order (project > user > built-in)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

