Contributing to peon-ping

Add a new sound pack

Sound packs are now hosted in their own GitHub repos and registered in the OpenPeon registry.

1. Create your pack

Create a new GitHub repo (e.g., yourname/openpeon-mypack) with this structure:

openpeon-mypack/
  openpeon.json
  sounds/
    SomeSound.wav
    AnotherSound.mp3
    ...
  README.md
  LICENSE

Audio formats: WAV, MP3, or OGG. Keep files small (game sound effects are ideal). Max 1 MB per file, 50 MB total.

2. Write the manifest

Create an openpeon.json mapping your sounds to CESP categories:

{
  "cesp_version": "1.0",
  "name": "my_pack",
  "display_name": "My Character",
  "version": "1.0.0",
  "author": { "name": "Your Name", "github": "yourname" },
  "license": "CC-BY-NC-4.0",
  "language": "en",
  "categories": {
    "session.start": {
      "sounds": [
        { "file": "sounds/Hello.mp3", "label": "Hello there" }
      ]
    },
    "task.acknowledge": {
      "sounds": [
        { "file": "sounds/OnIt.mp3", "label": "On it" }
      ]
    },
    "task.complete": {
      "sounds": [
        { "file": "sounds/Done.mp3", "label": "Done" }
      ]
    },
    "task.error": {
      "sounds": [
        { "file": "sounds/Oops.mp3", "label": "Oops" }
      ]
    },
    "input.required": {
      "sounds": [
        { "file": "sounds/NeedHelp.mp3", "label": "Need your help" }
      ]
    },
    "resource.limit": {
      "sounds": [
        { "file": "sounds/Blocked.mp3", "label": "Blocked" }
      ]
    },
    "user.spam": {
      "sounds": [
        { "file": "sounds/StopIt.mp3", "label": "Stop it" }
      ]
    }
  }
}

Categories explained:

Category	When it plays
session.start	Session starts ($ claude)
task.acknowledge	Claude acknowledges a task
task.complete	Claude finishes and is idle
task.error	Something fails
input.required	Claude needs tool approval
resource.limit	Resource limits hit
user.spam	User spams prompts (3+ in 10 seconds)

Not every category is required — just include the ones you have sounds for.

3. Tag a release

git tag v1.0.0
git push origin v1.0.0

4. Register your pack

Submit your pack to the OpenPeon registry:

1. Fork PeonPing/registry
2. Add your pack entry to index.json (keep alphabetical order — see registry CONTRIBUTING.md)
3. Open a pull request

Once merged, your pack will be installable by everyone and listed on openpeon.com/packs.

Automate pack creation

Have a single audio file with all your character's quotes? You can auto-transcribe and split it:

1. Copy .env.example to .env and add your Deepgram API key (or use Whisper locally)
2. Transcribe with word-level timestamps:

# Option A: Deepgram (cloud, fast)
source .env
curl --http1.1 -X POST \
  "https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&utterances=true&utt_split=0.8" \
  -H "Authorization: Token $DEEPGRAM_API_KEY" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @your_audio.mp3 -o transcription.json

# Option B: Whisper (local, free)
pip install openai-whisper
whisper your_audio.mp3 --model base --language en --output_format json --word_timestamps True --output_dir .

3. Use the timestamps from the JSON to cut individual clips with ffmpeg:

ffmpeg -i your_audio.mp3 -ss 0.0 -to 1.5 -c copy sounds/Quote1.mp3 -y
ffmpeg -i your_audio.mp3 -ss 2.0 -to 4.8 -c copy sounds/Quote2.mp3 -y
# ... repeat for each quote

4. Map the clips to categories in openpeon.json and you're done.

Contribute code

Bug fixes, new features, and IDE adapters are welcome as PRs to this repo. Sound packs should not be added here — use the registry flow above.

Run tests before submitting:

bats tests/

Pack ideas

Browse the full catalog at openpeon.com/packs for inspiration, or check the create guide for the complete walkthrough.