Your Peon pings you when Windsurf Cascade finishes working.
A Windsurf-compatible port of peon-ping. Plays Warcraft III Peon voice lines via Cascade hooks — so your IDE sounds like Orgrimmar.
- What you'll hear
- Prerequisites
- Install
- Uninstall
- Configuration
- Sound packs
- How it works
- Credits
- License
| Event | Sound | Examples |
|---|---|---|
| Cascade finishes responding | Complete | "Ready to work?", "Work, work.", "Something need doing?" |
| Cascade writes code | Acknowledge | "I can do that.", "Okie dokie.", "Be happy to." |
| Cascade runs a command | Acknowledge | "OK.", "Work, work." |
| Rapid prompts (3+ in 10s) | Easter egg | "Me busy, leave me alone!" |
Note
Examples above are from the default Orc Peon pack. More sound packs are available, including Human Peasant, Undead Acolyte, StarCraft, and Red Alert 2 characters.
- OS: macOS, Linux, or WSL2
- Python 3
- Windsurf with Cascade hooks support
- Audio playback tool (one of the following,
depending on your platform):
- macOS —
afplay(built-in) - Linux —
paplay(PulseAudio/PipeWire),aplay(ALSA),ffplay(FFmpeg), ormpv - WSL2 — PowerShell
MediaPlayer(uses Windows audio viapowershell.exe)
- macOS —
git clone https://github.com/ameshkov/peon-ping-windsurf.git ~/.peon-ping-windsurf
python3 ~/.peon-ping-windsurf/install.pyThe install script reads config.json to determine which
hooks to register, makes peon.py executable, and writes
the entries to ~/.codeium/windsurf/hooks.json (creating
it if needed, merging with existing hooks).
Restart Windsurf (or reload the window) and sounds will play automatically.
You can clone to any location — the script auto-detects
its own path. To add or remove hooks, edit config.json
and re-run python3 install.py.
If you prefer to configure hooks manually, create or edit
~/.codeium/windsurf/hooks.json (user-level) or
.windsurf/hooks.json (workspace-level):
{
"hooks": {
"post_cascade_response": [
{
"command": "python3 /path/to/peon.py --hook post_cascade_response",
"show_output": false
}
]
}
}python3 ~/.peon-ping-windsurf/uninstall.pyRemoves peon hooks from ~/.codeium/windsurf/hooks.json
and cleans up state. The repo itself is left in place —
delete it manually if you no longer need it.
Edit config.json in the repo directory
(e.g. ~/.peon-ping-windsurf/config.json):
{
"active_pack": "peon",
"volume": 1,
"enabled": true,
"hooks": {
"post_cascade_response": {
"enabled": true,
"categories": ["complete"]
},
"pre_user_prompt": {
"enabled": true,
"categories": ["greeting"]
},
"post_write_code": {
"enabled": true,
"categories": ["acknowledge"]
},
"post_run_command": {
"enabled": true,
"categories": ["acknowledge"]
}
},
"annoyed_threshold": 3,
"annoyed_window_seconds": 10
}- volume: 0.0–1.0
- enabled: set to
falseto mute everything - active_pack: which sound pack to use
- hooks: per-hook configuration:
- enabled: set to
falseto disable a specific hook - categories: list of sound categories to randomly pick from when the hook fires
- enabled: set to
- annoyed_threshold / annoyed_window_seconds: how many prompts in N seconds triggers the easter egg
Available categories: greeting, acknowledge,
complete, error, permission, resource_limit,
annoyed.
The annoyed category is special — include it in a
hook's categories list and it will only trigger when rapid
prompts exceed the threshold. Otherwise a random
non-annoyed category from the list is used.
| Pack | Character | By |
|---|---|---|
peon (default) |
Orc Peon (Warcraft III) | @tonyyont |
peon_fr |
Orc Peon (French) | @thomasKn |
peon_pl |
Orc Peon (Polish) | @askowronski |
peon_ru |
Orc Peon (Russian) | @maksimfedin |
peasant |
Human Peasant (Warcraft III) | @thomasKn |
peasant_fr |
Human Peasant (French) | @thomasKn |
peasant_ru |
Human Peasant (Russian) | @maksimfedin |
acolyte_ru |
Undead Acolyte (Russian) | @maksimfedin |
ra2_soviet_engineer |
Soviet Engineer (Red Alert 2) | @msukkari |
ra2_kirov |
Kirov Airship (Red Alert 2) | @i-zhirov |
sc_battlecruiser |
Battlecruiser (StarCraft) | @garysheng |
sc_kerrigan |
Sarah Kerrigan (StarCraft) | @garysheng |
sc_firebat |
Firebat (StarCraft) | @workdd |
sc_medic |
Medic (StarCraft) | @workdd |
sc_scv |
SCV (StarCraft) | @workdd |
sc_tank |
Siege Tank (StarCraft) | @workdd |
sc_terran |
Terran All Units (StarCraft) | @workdd |
sc_vessel |
Science Vessel (StarCraft) | @workdd |
Switch packs by editing config.json:
{ "active_pack": "sc_kerrigan" }peon.py is registered as a Windsurf Cascade hook. On each event it:
- Reads the
--hookargument to determine which hook fired - Looks up the hook in
config.jsonto get the list of candidate categories - Picks a random category, then a random voice line from it (avoiding repeats)
- Plays it via
afplay(macOS),paplay/aplay/ffplay/mpv(Linux), or PowerShellMediaPlayer(WSL2)
Sound files are property of their respective publishers (Blizzard Entertainment, EA) and are included for convenience.