Skip to content
Docs menu

Sounds

Hear when venom is done, failed or needs approval, pick or replace the sounds, set quiet hours and choose the player.

View .md

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 one

In 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.