herdr-sound-switch-plugin — switch Herdr's notification sounds to chiptune packs (mario, zelda, sonic, tetris, pacman, ff)

[hhstore]

herdr-sound — switch Herdr's notification sounds to chiptune packs (mario, zelda, sonic, tetris, pacman, ff)

Hi all — I made a small CLI that swaps Herdr's notification sounds for game-style chiptune packs, and thought I'd share it here.

Why

Herdr's built-in sounds are fine, but I run several agents in background workspaces all day and wanted to tell "finished" from "needs me" without looking at the screen. Herdr already supports custom mp3s natively via [ui.sound], but juggling done_path / request_path by hand gets old fast, especially if you want to try a few different sounds.

So this is deliberately not a plugin. No event hooks, no background process, no sound played by a third party that can double up with Herdr's own. It just does the boring plumbing on top of the feature Herdr already has:

• copies the pack's mp3s next to your config,
• points ui.sound.done_path / ui.sound.request_path at them,
• runs herdr server reload-config so it takes effect without a restart.

Because it's plain config, there's nothing running in the background and nothing to uninstall beyond hsp restore.

What you get

Six packs, each with two distinct sounds — one for done, one for blocked:

Pack	done	blocked
mario	bright two-note jump up	classic falling three-note
zelda	five-note rising arpeggio	descending resolve
sonic	fast high double-tap	descending sting with retrigger
tetris	quick rising sweep	five-note minor descent
pacman	rapid alternating "waka"	eleven-note chromatic slide
ff	fanfare arpeggio with a held top note	slow low descent

$ hsp list
   ff        1.68s
 * mario     1.06s
   pacman    1.21s
   sonic     1.26s
   tetris    1.23s
   zelda     1.61s

Every pack is original audio, synthesized from square waves by a generator script in the repo — the notes and rhythms are original compositions in a genre style, and no samples from any game are included. That keeps the whole package freely redistributable (Apache-2.0).

Other bits:

• Cross-platform. macOS, Linux and Windows — it locates your config exactly the way Herdr does, including %APPDATA%\herdr on Windows and $HERDR_CONFIG_PATH as an override.
• Never clobbers your config. Edits are done with tomlkit, so your comments and formatting survive. hsp restore returns you to Herdr defaults and only deletes the files it installed itself.
• hsp doctor — a one-shot health check: finds the herdr binary, validates the config, and verifies the active pack's files are actually there. Handy right after installing, and it warns you in advance if you're on Linux with no supported audio player.

Install

Requires Python 3.10+ and Herdr 0.9.3+.

uv tool install herdr-sound

pip install herdr-sound works too, or straight from git for unreleased changes:

uv tool install --from git+https://github.com/ezstack-dev/herdr-sound-plugin herdr-sound

Installs both herdr-sound and the short alias hsp.

On Linux, Herdr plays mp3s through whichever of paplay / pw-play / ffplay / mpg123 / mpv it finds first — so if you've never heard a Herdr sound on Linux, that's usually the missing piece (apt install pulseaudio-utils or pipewire-audio).

Use

hsp list              # list packs, * marks the active one
hsp use zelda         # switch pack
hsp status            # what's active, and where the files are
hsp doctor            # health check
hsp restore           # back to Herdr defaults (disable sound, remove copies)

That's it — no restart needed.

Repo

https://github.com/ezstack-dev/herdr-sound-plugin — Apache-2.0, on PyPI as herdr-sound. English and 中文 READMEs, and notes on the platform/audio-player details.

Two things worth knowing

Both are Herdr behaviours rather than limitations of this tool, but they surprised me enough to be worth stating up front:

1. Sounds play in the Herdr client, not the server. If you run headless or only attach through a bridge, the config is still correct — you just won't hear anything until a real client is attached.
2. There is no "failed" sound, because Herdr's agent states are idle / working / blocked / done / unknown. An agent that errors out usually still finishes as done, so it gets the finish sound. I map the "something's wrong" sound onto blocked since that's the closest slot available — but if a distinct failed state ever landed, this would be the natural place to put it.

Feedback, pack ideas (or a better-sounding blocked for any pack) welcome — the note tables are a single readable Python dict, so adding a pack is more or less transcribing a few notes.