agent-sounds

Tiny local sound runtime for agent events.

No preset = no sound.

Install

curl -fsSL https://raw.githubusercontent.com/hzoo/agent-sounds/main/install.sh | bash

Dependencies:

• jq
• ffplay (use ffplay for .ogg; afplay support is unreliable)

Remove

rm -f ~/.local/bin/agent-sounds
rm -rf "${XDG_STATE_HOME:-$HOME/.local/state}/agent-sounds"
rm -rf ~/.agent-sounds

Runtime Commands

• agent-sounds ls
• agent-sounds use <preset>
• agent-sounds info
• agent-sounds events
• agent-sounds play <event>
• agent-sounds vol <0-1>
• agent-sounds cur

Preset Quickstart (Required)

mkdir -p ~/.agent-sounds/presets/my-first/sounds
cp /path/to/sound.wav ~/.agent-sounds/presets/my-first/sounds/notification.wav
cat > ~/.agent-sounds/presets/my-first/preset.json <<'JSON'
{
  "name": "My First",
  "sounds": {
    "notification": [{ "file": "sounds/notification.wav" }]
  }
}
JSON
agent-sounds use my-first
agent-sounds play notification

Sounds are not bundled. Fetch/copy files from external sources into:

• ~/.agent-sounds/presets/<preset>/sounds/
• ~/.agent-sounds/presets/<preset>/preset.json

State config file:

• ${XDG_STATE_HOME:-~/.local/state}/agent-sounds/config

Canonical References

• Skill entry: skills/agent-sounds/SKILL.md
• Reference files: skills/agent-sounds/references/*
• Optional external recipes (not runtime): preset fetch scripts gist

Codex note:

• As of codex-cli 0.101.0 (2026-02-12), external notify fires on agent-turn-complete only.