Sounds
Hear when venom is done, failed or needs approval, pick or replace the sounds, set quiet hours and choose the player.
The TUI plays a sound for venom's events out of the box, so you know when to look at the terminal. The built-in sounds are synthesized in code (no recordings, nothing downloaded) and cached as small WAV files in ~/.venom/cache/sounds/ the first time they play. Only the TUI plays sounds: venom -p, venom serve and venom acp do not (hooks still run).
Quick start
venom sounds list # the built-ins, your settings, the player venom will use
venom sounds list --play chime # preview oneIn a session: /sounds lists them, previews the one you pick and mutes or unmutes; /sounds play <name|path|event> previews; /sounds mute, /sounds unmute and /sounds toggle apply to this session. The leader then n (ctrl+g n) toggles mute.
Configuration
sounds:
enabled: true
volume: 0.6
only_when_unfocused: true
quiet_hours: "22:00-08:00"
min_turn_seconds: 5
events:
main_agent_done: chime
subagent_done: tick
step_done: off
permission_needed: attention
agent_failed: ~/sounds/sad-trombone.mp3
schedule_done: done| Key | Type | Default | What |
|---|---|---|---|
sounds |
object | the section | |
sounds.enabled |
boolean | true |
false turns every event sound off |
sounds.volume |
number 0 to 1 | 0.6 |
playback volume |
sounds.only_when_unfocused |
boolean | true |
play only while the terminal is in the background |
sounds.quiet_hours |
"HH:MM-HH:MM" |
none | local time, may wrap midnight; no sounds inside it |
sounds.min_turn_seconds |
number | 5 |
no main_agent_done sound for a run shorter than this (an error always sounds) |
sounds.events |
object | below | a built-in name, an absolute path (~/ works) or off, per event |
sounds.events.main_agent_done |
string | chime |
MainAgentDone |
sounds.events.subagent_done |
string | tick |
SubagentDone |
sounds.events.step_done |
string | off |
StepDone (pop is a good choice) |
sounds.events.permission_needed |
string | attention |
PermissionNeeded |
sounds.events.agent_failed |
string | failure |
AgentFailed |
sounds.events.schedule_done |
string | done |
ScheduleDone |
| Environment variable | What |
|---|---|
VENOM_SOUND_PLAYER |
your own player command (mpv --no-video, ffplay -nodisp -autoexit); the file path is appended |
A hook with sound: plays a sound for a narrower case, for example one sound per subagent role.
Built-in sounds
| Name | Sound | Default for |
|---|---|---|
chime |
a clear two-note chime (1.2 s) | main agent done |
tick |
a soft tick (0.07 s) | subagent done |
attention |
two gentle pulses (0.5 s) | permission needed |
failure |
a low falling two-tone (0.7 s) | agent failed |
done |
a short rising two-tone | schedule done |
pop |
a quick pop (0.1 s) | |
bell |
a small bell with a long ring | |
hiss |
a cobra's hiss | |
success |
a rising major arpeggio | |
marimba |
a woody descending pair |
Your own sounds: any audio file by absolute path (.wav, .mp3, .aiff, .m4a, .ogg, .flac); what plays depends on the player.
Playback per platform
| Where | How |
|---|---|
| macOS | afplay (wav, aiff, mp3, m4a) |
| Linux | the first of pw-play, paplay, aplay (wav only) on PATH |
| WSL, Windows | powershell.exe with Media.SoundPlayer (wav only) |
over ssh (SSH_CONNECTION, SSH_CLIENT, SSH_TTY) or no player found |
the terminal bell, plus a desktop notification escape where the terminal supports one (OSC 9, 777 or 99) |
The player runs detached, never blocks the agent, and is killed after 10 seconds. A missing player or a broken file is silent.
When a sound does not play
Sounds are off or muted for the session, the event is off, the volume is 0, it is quiet hours, the terminal has focus (with only_when_unfocused), a MainAgentDone run was shorter than min_turn_seconds, or you stopped the run with Esc.
Focus detection asks the terminal for focus reports (CSI ?1004h). iTerm2, Ghostty, kitty, WezTerm, Alacritty, foot, Windows Terminal, VS Code and tmux with focus-events on send them. A terminal that sends none counts as unfocused, so you still hear sounds.