pingthings 0.1.0

package/LICENSE

@@ -0,0 +1,11 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+Audio assets are from Seven Kingdoms: Ancient Adversaries
+Copyright 1997,1998 Enlight Software Ltd.
+Licensed under GPL v2.

package/README.md

@@ -0,0 +1,262 @@
+# pingthings
+
+Notification sounds for Claude Code and other CLI tools. Like text tones for your terminal.
+
+Pick a sound pack, and pingthings plays a random sound whenever Claude Code needs your attention. Or use **informational mode** to hear different sounds for different events — know if a task is done, if something went wrong, or if Claude needs your input, all by ear.
+
+## Install
+
+```bash
+npm install -g pingthings
+```
+
+## Quick start
+
+```bash
+# Play a random sound from the active pack
+pingthings play
+
+# See available packs
+pingthings list
+
+# Switch packs
+pingthings use 7kaa-soldiers
+
+# Preview a pack
+pingthings preview 7kaa-soldiers
+
+# Play a specific sound
+pingthings play READY
+
+# Play event-based sounds (informational mode)
+pingthings play --event done
+pingthings play --event error
+pingthings play -e complete
+```
+
+## Claude Code setup
+
+### Basic (random sounds)
+
+Add this to your `~/.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pingthings play"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### Informational (event-based sounds)
+
+For different sounds based on what Claude is doing, set up multiple hooks:
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pingthings play --event permission"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pingthings play --event complete"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pingthings play --event error"
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "pingthings play --event blocked"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+| Claude Code Event | Sound Event | When it fires |
+|---|---|---|
+| `Notification` | `permission` | Claude needs your input or approval |
+| `Stop` | `complete` | Claude finishes a response |
+| `PostToolUseFailure` | `error` | A tool fails (bash error, etc.) |
+| `StopFailure` | `blocked` | API error, rate limit, auth issue |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `pingthings play [sound] [--event type]` | Play a sound (random, specific, or event-based) |
+| `pingthings list` | Show available sound packs |
+| `pingthings use <pack>` | Set the active sound pack |
+| `pingthings preview <pack>` | Preview a random sound from a pack |
+| `pingthings config [key] [val]` | Show or update configuration |
+| `pingthings install <pack>` | Install a sound pack (coming soon) |
+
+## Configuration
+
+Config lives at `~/.config/pingthings/config.json`:
+
+```json
+{
+  "activePack": "7kaa-soldiers",
+  "mode": "random",
+  "specificSound": null
+}
+```
+
+- **activePack** — which sound pack to use
+- **mode** — `"random"` (default), `"specific"`, or `"informational"`
+- **specificSound** — sound name to always play when mode is `"specific"`
+
+Set values via CLI:
+
+```bash
+pingthings config mode random          # any random sound
+pingthings config mode specific        # always the same sound
+pingthings config mode informational   # event-based sounds
+pingthings config specificSound READY  # set the sound for specific mode
+```
+
+## Modes
+
+### Random (default)
+Plays any random sound from the active pack. Great for variety.
+
+### Specific
+Always plays the same configured sound. Set it with `pingthings config specificSound <name>`.
+
+### Informational
+Plays different sounds based on what's happening. Use the `--event` flag to tell pingthings what type of event occurred:
+
+| Event | Meaning | Example trigger |
+|-------|---------|----------------|
+| `done` | Task/step finished | Claude completed a request |
+| `permission` | Needs approval | Claude needs tool permission |
+| `complete` | Major milestone done | Project or phase finished |
+| `error` | Something went wrong | Build failed, test failed |
+| `blocked` | User action needed | Need to update a dashboard, grant access |
+
+```bash
+pingthings play --event done       # "task finished" sound
+pingthings play --event error      # "something broke" sound
+pingthings play -e permission      # "need your approval" sound
+```
+
+Each pack maps its sounds to events thematically:
+- **7kaa-soldiers**: voice acknowledgements for done, "READY" for permission, attack grunts for errors
+- **openarena-announcer**: "excellent!" for done, "prepare!" for permission, "denied!" for errors
+- **wesnoth-combat**: gold collect for done, chest open for permission, explosions for errors
+- **freedoom-arsenal**: item pickup for done, shotgun cock for permission, barrel explosion for errors
+- **warzone2100-command**: "research completed" for done, "incoming transmission" for permission, "mission failed" for errors
+- **0ad-civilizations**: Greek "as you wish" for done, "my lord?" for permission, alarm horns for errors
+
+## Built-in packs
+
+### 7kaa-soldiers
+Soldier acknowledgement voice lines from **Seven Kingdoms: Ancient Adversaries** — 53 sounds from all 10 civilizations (Norman, Maya, Greek, Viking, Persian, Chinese, Japanese, Egyptian, Indian, Zulu). License: GPL v2.
+
+### wesnoth-combat
+Fantasy combat and magic sounds from **Battle for Wesnoth** — 19 sounds including swords, bows, spells, explosions, gold collection, healing, and a dwarf laugh. License: GPL v2+.
+
+### openarena-announcer
+Arena FPS announcer voice lines from **OpenArena** — 18 sounds including "excellent!", "impressive!", "fight!", "perfect!", "denied!", and more. License: GPL v2.
+
+### freedoom-arsenal
+Retro FPS weapon and pickup sounds from **Freedoom** — 19 sounds including shotgun, plasma rifle, BFG, rocket launcher, item pickups, and teleport. License: BSD-3-Clause.
+
+### warzone2100-command
+Sci-fi military commander voice lines from **Warzone 2100** — 21 sounds including "research completed", "mission successful", "incoming transmission", "enemy detected", and NEXUS AI laughs. License: GPL v2.
+
+### 0ad-civilizations
+Ancient civilization voice lines and alerts from **0 A.D.** — 28 sounds with Greek, Latin, and Persian voice acknowledgements ("my lord", "as you wish", "by your order") plus alarm sounds (victory, defeat, attack). License: CC-BY-SA 3.0.
+
+## Custom packs
+
+Place packs in `~/.config/pingthings/packs/<pack-name>/`:
+
+```
+my-pack/
+  manifest.json
+  sounds/
+    sound1.wav
+    sound2.wav
+```
+
+Minimal `manifest.json`:
+
+```json
+{
+  "name": "my-pack",
+  "description": "My custom sound pack",
+  "license": "MIT",
+  "credits": "Your Name"
+}
+```
+
+The `sounds` field in the manifest is optional — if omitted, all `.wav`, `.mp3`, `.ogg`, and `.flac` files in the `sounds/` directory are used.
+
+To support informational mode, add an `events` field mapping event types to sounds:
+
+```json
+{
+  "name": "my-pack",
+  "description": "My custom sound pack",
+  "license": "MIT",
+  "credits": "Your Name",
+  "events": {
+    "done": ["sounds/success.wav", "sounds/complete.wav"],
+    "permission": ["sounds/question.wav"],
+    "complete": ["sounds/fanfare.wav"],
+    "error": ["sounds/alarm.wav", "sounds/buzz.wav"],
+    "blocked": ["sounds/warning.wav"]
+  }
+}
+```
+
+## Requirements
+
+- Node.js >= 18
+- macOS (`afplay`) or Linux (`paplay` / `aplay`)
+
+## License
+
+GPL v2 — includes audio from [Seven Kingdoms: Ancient Adversaries](https://github.com/the3dfxdude/7kaa) (GPL v2).

package/bin/pingthings.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+const commands = {
+  play: () => import('../src/cli/play.js'),
+  list: () => import('../src/cli/list.js'),
+  use: () => import('../src/cli/use.js'),
+  preview: () => import('../src/cli/preview.js'),
+  config: () => import('../src/cli/config.js'),
+  install: () => import('../src/cli/install.js'),
+};
+
+function showHelp() {
+  console.log(`
+pingthings v${pkg.version} — ${pkg.description}
+
+Usage: pingthings <command> [options]
+
+Commands:
+  play [sound]       Play a sound from the active pack (random by default)
+  list               Show available sound packs
+  use <pack>         Set the active sound pack
+  preview <pack>     Preview a random sound from a pack
+  config [key] [val] Show or update configuration
+  install <pack>     Install a sound pack (coming soon)
+
+Options:
+  --help, -h         Show this help message
+  --version, -v      Show version number
+
+Modes:
+  random             Play any random sound (default)
+  specific           Always play the same configured sound
+  informational      Play sounds mapped to event types
+
+Examples:
+  pingthings play                  Play a random sound
+  pingthings play 00083-READY     Play a specific sound
+  pingthings play --event done    Play a "task done" sound
+  pingthings play -e error        Play an "error" sound
+  pingthings list                  List all available packs
+  pingthings use 7kaa-soldiers    Switch to a pack
+  pingthings config mode informational   Enable event-based sounds
+`);
+}
+
+if (!command || command === '--help' || command === '-h') {
+  showHelp();
+  process.exit(0);
+}
+
+if (command === '--version' || command === '-v') {
+  console.log(pkg.version);
+  process.exit(0);
+}
+
+if (!commands[command]) {
+  console.error(`Unknown command: ${command}`);
+  console.error('Run "pingthings --help" for usage.');
+  process.exit(1);
+}
+
+try {
+  const mod = await commands[command]();
+  await mod.default(args);
+} catch (err) {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "pingthings",
+  "version": "0.1.0",
+  "description": "Notification sounds for Claude Code and other CLI tools",
+  "type": "module",
+  "license": "GPL-2.0",
+  "bin": {
+    "pingthings": "./bin/pingthings.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "packs/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "claude-code",
+    "notification",
+    "sound",
+    "cli",
+    "hook"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JustPinero/pingthings.git"
+  },
+  "homepage": "https://github.com/JustPinero/pingthings",
+  "author": "Justin Pinero"
+}

package/packs/0ad-civilizations/manifest.json

@@ -0,0 +1,77 @@
+{
+  "name": "0ad-civilizations",
+  "description": "Ancient civilization voice lines and alerts from 0 A.D.",
+  "version": "1.0.0",
+  "license": "CC-BY-SA-3.0",
+  "credits": "Wildfire Games / 0 A.D. (https://github.com/0ad/0ad) — audio licensed under CC-BY-SA 3.0",
+  "sounds": [
+    "sounds/alarm-alert.wav",
+    "sounds/alarm-attack.wav",
+    "sounds/alarm-defeat.wav",
+    "sounds/alarm-no-resource.wav",
+    "sounds/alarm-objective.wav",
+    "sounds/alarm-research-complete.wav",
+    "sounds/alarm-victory.wav",
+    "sounds/greek-as-you-wish.wav",
+    "sounds/greek-attack-1.wav",
+    "sounds/greek-build-1.wav",
+    "sounds/greek-heal-1.wav",
+    "sounds/greek-march-1.wav",
+    "sounds/greek-my-lord-1.wav",
+    "sounds/greek-my-lord-2.wav",
+    "sounds/greek-retreat-1.wav",
+    "sounds/greek-what-is-it-1.wav",
+    "sounds/greek-yes.wav",
+    "sounds/latin-attack-1.wav",
+    "sounds/latin-build-1.wav",
+    "sounds/latin-fight-1.wav",
+    "sounds/latin-heal-1.wav",
+    "sounds/latin-hello-1.wav",
+    "sounds/latin-my-lord-1.wav",
+    "sounds/latin-what-is-it.wav",
+    "sounds/persian-attack-1.wav",
+    "sounds/persian-by-your-order.wav",
+    "sounds/persian-forward-1.wav",
+    "sounds/persian-i-will-go.wav"
+  ],
+  "events": {
+    "done": [
+      "sounds/greek-as-you-wish.wav",
+      "sounds/greek-yes.wav",
+      "sounds/greek-build-1.wav",
+      "sounds/latin-build-1.wav",
+      "sounds/persian-by-your-order.wav",
+      "sounds/persian-i-will-go.wav",
+      "sounds/alarm-research-complete.wav"
+    ],
+    "permission": [
+      "sounds/greek-my-lord-1.wav",
+      "sounds/greek-my-lord-2.wav",
+      "sounds/greek-what-is-it-1.wav",
+      "sounds/latin-my-lord-1.wav",
+      "sounds/latin-what-is-it.wav",
+      "sounds/latin-hello-1.wav",
+      "sounds/alarm-objective.wav"
+    ],
+    "complete": [
+      "sounds/alarm-victory.wav",
+      "sounds/greek-march-1.wav",
+      "sounds/greek-heal-1.wav",
+      "sounds/latin-heal-1.wav",
+      "sounds/persian-forward-1.wav"
+    ],
+    "error": [
+      "sounds/alarm-attack.wav",
+      "sounds/alarm-defeat.wav",
+      "sounds/alarm-no-resource.wav",
+      "sounds/greek-attack-1.wav",
+      "sounds/latin-attack-1.wav",
+      "sounds/persian-attack-1.wav"
+    ],
+    "blocked": [
+      "sounds/alarm-alert.wav",
+      "sounds/greek-retreat-1.wav",
+      "sounds/latin-fight-1.wav"
+    ]
+  }
+}

package/packs/7kaa-soldiers/manifest.json

@@ -0,0 +1,111 @@
+{
+  "name": "7kaa-soldiers",
+  "description": "Soldier acknowledgement voice lines from Seven Kingdoms: Ancient Adversaries",
+  "version": "1.0.0",
+  "license": "GPL-2.0",
+  "credits": "Enlight Software Ltd. / Seven Kingdoms: Ancient Adversaries (https://github.com/the3dfxdude/7kaa)",
+  "sounds": [
+    "sounds/00001-CH_A2.wav",
+    "sounds/00006-NO_V2.wav",
+    "sounds/00007-NO_V3.wav",
+    "sounds/00008-MA_V1.wav",
+    "sounds/00009-GR_V2.wav",
+    "sounds/00010-GR_V3.wav",
+    "sounds/00011-VI_V1.wav",
+    "sounds/00012-NO_A1.wav",
+    "sounds/00012-VI_V2.wav",
+    "sounds/00013-GR_V1.wav",
+    "sounds/00013-NO_A2.wav",
+    "sounds/00014-MA_A1.wav",
+    "sounds/00014-PE_V1.wav",
+    "sounds/00015-GR_A1.wav",
+    "sounds/00015-MA_V2.wav",
+    "sounds/00016-MA_V3.wav",
+    "sounds/00016-VI_A1.wav",
+    "sounds/00017-MA_V4.wav",
+    "sounds/00017-VI_A2.wav",
+    "sounds/00018-PE_A2.wav",
+    "sounds/00018-PE_V2.wav",
+    "sounds/00019-PE_V3.wav",
+    "sounds/00020-PE_A1.wav",
+    "sounds/00020-PE_V4.wav",
+    "sounds/00021-CH_A1.wav",
+    "sounds/00021-CH_V1.wav",
+    "sounds/00022-CH_V2.wav",
+    "sounds/00022-JA_A1.wav",
+    "sounds/00023-CH_V3.wav",
+    "sounds/00023-JA_A2.wav",
+    "sounds/00024-CH_V4.wav",
+    "sounds/00025-CH_V5.wav",
+    "sounds/00026-JA_V1.wav",
+    "sounds/00027-JA_V2.wav",
+    "sounds/00028-JA_V3.wav",
+    "sounds/00029-JA_V4.wav",
+    "sounds/00030-JA_V5.wav",
+    "sounds/00035-MA_V5.wav",
+    "sounds/00083-READY.wav",
+    "sounds/00084-NO_V1.wav",
+    "sounds/00085-EG_V1.wav",
+    "sounds/00086-EG_V2.wav",
+    "sounds/00087-EG_V3.wav",
+    "sounds/00088-EG_V4.wav",
+    "sounds/00089-IN_V1.wav",
+    "sounds/00090-IN_V2.wav",
+    "sounds/00091-IN_V3.wav",
+    "sounds/00092-IN_V4.wav",
+    "sounds/00093-ZU_V2.wav",
+    "sounds/00094-ZU_V3.wav",
+    "sounds/00095-ZU_V5.wav",
+    "sounds/00096-ZU_V7.wav",
+    "sounds/00097-ZU_V8.wav"
+  ],
+  "events": {
+    "done": [
+      "sounds/00006-NO_V2.wav",
+      "sounds/00008-MA_V1.wav",
+      "sounds/00009-GR_V2.wav",
+      "sounds/00011-VI_V1.wav",
+      "sounds/00014-PE_V1.wav",
+      "sounds/00021-CH_V1.wav",
+      "sounds/00026-JA_V1.wav",
+      "sounds/00084-NO_V1.wav",
+      "sounds/00085-EG_V1.wav",
+      "sounds/00089-IN_V1.wav",
+      "sounds/00093-ZU_V2.wav"
+    ],
+    "permission": [
+      "sounds/00083-READY.wav",
+      "sounds/00013-GR_V1.wav",
+      "sounds/00018-PE_V2.wav",
+      "sounds/00022-CH_V2.wav",
+      "sounds/00027-JA_V2.wav",
+      "sounds/00090-IN_V2.wav"
+    ],
+    "complete": [
+      "sounds/00007-NO_V3.wav",
+      "sounds/00010-GR_V3.wav",
+      "sounds/00016-MA_V3.wav",
+      "sounds/00019-PE_V3.wav",
+      "sounds/00023-CH_V3.wav",
+      "sounds/00028-JA_V3.wav",
+      "sounds/00087-EG_V3.wav",
+      "sounds/00091-IN_V3.wav"
+    ],
+    "error": [
+      "sounds/00001-CH_A2.wav",
+      "sounds/00012-NO_A1.wav",
+      "sounds/00013-NO_A2.wav",
+      "sounds/00014-MA_A1.wav",
+      "sounds/00015-GR_A1.wav",
+      "sounds/00016-VI_A1.wav",
+      "sounds/00018-PE_A2.wav",
+      "sounds/00021-CH_A1.wav",
+      "sounds/00022-JA_A1.wav"
+    ],
+    "blocked": [
+      "sounds/00017-VI_A2.wav",
+      "sounds/00020-PE_A1.wav",
+      "sounds/00023-JA_A2.wav"
+    ]
+  }
+}