Purrd: music while the agent works, silence when it is done

You start a build or hand a task to an agent, and then you watch the terminal. Or you look away, forget it, and come back an hour late. Purrd turns waiting into sound: music plays while the work runs, and silence returns when it stops. A beep is easy to miss; the end of music is not.

What you get. Your ears keep watch for you. Sound means working, silence means done, a short voice line means "the agent is waiting for you". Five commands to install, GPL licence, no model, no network.

1. Install and try

git clone https://your-forge/purrd.git && cd purrd
uv sync
uv run purrd demo          # listen to the loop, Ctrl+C to stop
uv run purrd make -j8      # music during the build; silence = done

It needs a system audio player and picks the one present: PipeWire (pw-cat), ALSA (aplay) or ffmpeg (ffplay).

2. Wrap any command

purrd ./long-script.sh               # any command
purrd --seed 3 ./run.sh              # another seed, another melody
purrd --style noir pytest            # classic, chill, drive, noir, minimal

The music is generated, not a playlist: a style picks its drum patterns, bass riffs and scale, and the seed varies the melody. Two sessions never sound exactly alike, so it never becomes a tic you stop hearing.

3. Follow a coding agent

For Claude Code, purrd runs as a small daemon driven by the agent's hooks: the start of a task starts the music, the end stops it.

purrd start     # in the hook that fires when the agent starts working
purrd stop      # in the hook that fires when it stops

Optional voices speak short lines on four events: start, done, permission asked, error. They come from community sound packs in the CESP format; purrd picks a line by the event's category and at random, so the same sentence does not come back every time.

purrd import-pack ~/Downloads/peon
purrd say permission

4. Your own tracks

Prefer finished music? Drop audio files in an "ambience bank" folder and set the mix: purrd bank ratio 0.5 plays half bank, half generated. An empty bank silently falls back to the generator.

Traps

Sound plays where purrd runs. Our agent ran on a headless server: for days purrd played to an empty room, and we thought the hook did not fire. When you drive the agent from a browser, have the hooks declare the state to the page, and let the page play.

A page left open for hours does not reload its script after you deploy a new one. Force a reload before looking for a bug.

Found this useful? Tell us what to measure next.