sounds

---

What It Does

Agent Sounds hooks into Claude Code's lifecycle events and plays audio cues so you know what's happening without watching the terminal.

4 original sound packs. 38 royalty-free sounds. Zero copyrighted audio. Works on macOS, Linux, and Windows.

Event	When It Fires	Sound
Session Start	You open Claude Code	Boot / greeting chime
Prompt Submit	You send a message	Acknowledgment blip
Subagent Start	A subagent spawns	Work sound
Plan Mode	Enter / exit plan mode	Work / done
Task Complete	Claude finishes responding	Success tone
Permission Request	Claude needs your approval	Alert / attention

All sounds play in the background — they never block Claude Code.

---

Quick Start

Option A: One command (via agentmag CLI)

npx agentmag add tool claude-sounds

Option B: npm global install

npm install -g @agentmag/sounds

Option C: Claude Code plugin marketplace

claude plugin install sounds@Agent-mag

---

Sound Packs

Pack	Vibe	Sounds
terminal-hacker	Sci-fi hacking — boot sequences, data streams, digital alerts	10
retro-synth	80s synthwave — warm pads, arpeggios, analog warmth	10
minimal-tones	Clean beeps and chimes — subtle, professional, non-distracting	9
nature-ambient	Forest and water — wind chimes, water drops, bird chirps	9

All packs are enabled by default. Mix and match to your preference.

All sounds are generated via Python waveform synthesis (sine waves, square waves, envelope shaping) — no copyrighted game audio, no licensing issues.

---

CLI Commands

agent-sounds status              # Show current config
agent-sounds packs               # List available sound packs
agent-sounds enable <pack>       # Enable a sound pack
agent-sounds disable <pack>      # Disable a sound pack
agent-sounds volume 0.5          # Set volume (0.0 to 1.0)
agent-sounds mute                # Mute all sounds
agent-sounds unmute              # Unmute all sounds
agent-sounds test                # Play all event sounds
agent-sounds test ready          # Play a specific event
agent-sounds reset               # Reset config to defaults

---

Configuration

Config is stored in config.json in the package root:

{
  "enabled": ["terminal-hacker", "retro-synth", "minimal-tones", "nature-ambient"],
  "volume": 0.25,
  "muted": false
}

---

Create Custom Sound Packs

1. Create a directory under sounds/ with your pack name
2. Add audio files (.wav or .mp3)
3. Create a source.json mapping events to files:

{
  "ready": ["my-start-sound.wav"],
  "work": ["working-01.wav", "working-02.wav"],
  "done": ["complete.wav"],
  "ask": ["attention.wav"]
}

4. Enable it: agent-sounds enable my-pack

---

How Claude Code Sounds Work

Claude Code supports hooks — shell commands that execute on lifecycle events. Agent Sounds registers hooks for 7 events that trigger play.sh, which:

1. Reads your config (enabled packs, volume, muted state)
2. Collects matching audio files from all enabled packs
3. Picks one at random
4. Plays it in the background via your OS audio player

The entire plugin is bash scripts + audio files. No Node.js runtime, no heavy dependencies.

Requirements

• Python 3 — for JSON parsing in shell scripts
• Audio player — auto-detected per platform:

Platform	Player
macOS	afplay (built-in)
Linux	pw-play → paplay → ffplay
Windows	ffplay → PowerShell MediaPlayer

---

Comparison