Your coding agent says Work complete! when it finishes and We need more gold! when your usage runs out. Codex gets a Peon or a Peasant to keep it company.
Hear every clip and meet the pets · Event map · Download the Peon · Download the Peasant · Web pet atlases · Releases · Agent Navi · Agent Johnny 5 · Agent Rocky · Agent Star Wars · Agent StarCraft
![]() Idle |
![]() Working |
![]() Waiting |
![]() Review |
![]() Blocked |
![]() Idle |
![]() Working |
![]() Waiting |
![]() Review |
![]() Blocked |
![]() Session start |
![]() Turn finished |
![]() Destructive command |
![]() Out of usage |
![]() Prompt spam |
![]() Alliance |
Warcraft peon sound notifications for coding agents and two independent Codex pets. Native sound integrations for Claude Code, Codex, and Gemini CLI, plus a small event interface for other agents and scripts. One shared player supports macOS, Linux, and Windows. The orc Peon and human Peasant pets use Codex's native animation and activity states.
Agent Warcraft plays 56 Warcraft III voice lines on agent events:
- "Ready to work." when a session starts and "Work work." when you send a prompt.
- "What you want?" when an approval is waiting, and "We're under attack!" when
that approval is for
rm -rf, a force push, or a dropped table. - "Work complete!" when a turn finishes.
- "We need more gold!" when Claude Code stops on a rate limit or billing error.
- "Me busy, leave me alone!" when you send three prompts in ten seconds, exactly as a peon reacts to being clicked too often.
Pick the Horde (peon, grunt, and orc advisor; the default) or the Alliance (peasant, footman, and knight: "Job's done!", "More gold is required."), or mix both. It runs locally, sends no telemetry, and never approves or blocks an agent's actions.
A sibling of Agent Navi, Agent Johnny 5, Agent Rocky, Agent Star Wars, and Agent StarCraft, inspired by thephw/claude-meseeks. For a large multi-game sound pack registry, see peon-ping.
| Choice | Install | Requirements |
|---|---|---|
| Sounds | Agent plugin or standalone CLI | Node.js 22+ and local audio |
| Gold and food meters | Status line command | Claude Code status line |
| Codex pets | Pet installer or manual ZIP | A host with compatible custom pets |
Installing the sound plugin never installs or selects a pet, and never changes your status line.
- Node.js 22 or newer, with
nodeon the agent'sPATH. - macOS: built-in
afplay. - Linux:
paplay,pw-play,aplay, orffplay, with a working local audio device. - Windows: Windows PowerShell (
powershell.exe), usingSystem.Media.SoundPlayer.
No npm runtime dependencies, Bash, or jq are required. Windows hooks and audio
playback do not require Git Bash. A headless machine without an audio device
cannot play sounds on your laptop automatically.
claude plugin marketplace add mitchtech/agent-warcraft
claude plugin install warcraft@agent-warcraftInside a Claude Code session, the same steps are /plugin marketplace add and
/plugin install.
codex plugin marketplace add mitchtech/agent-warcraft
codex plugin add warcraft@agent-warcraftReview and trust the installed hooks in Codex's hook settings before using them. Installing or enabling the plugin does not automatically trust its hook commands. Restart the agent after installation or updates.
gemini extensions install https://github.com/mitchtech/agent-warcraftGemini selects a self-contained ZIP for your platform from GitHub Releases. Review the extension's hook consent prompt and restart Gemini. For local development:
npm run gemini
gemini extensions link ./dist/geminiThe repository root is for shared sources and discovery; Gemini's executable hook file is included in the generated extension, not the source root. Install published release assets rather than linking the repository root or a raw Git branch. See Gemini integration.
Agent Navi, Agent Johnny 5, Agent Rocky, Agent Star Wars, and Agent StarCraft
respond to the same events. Enable one per host unless you want a fairy, a robot,
a peon, an Eridian, two droids, and an SCV talking over each other. For example,
claude plugin disable johnny5@agent-johnny5 for Claude Code, or
enabled = false under [plugins."johnny5@agent-johnny5"] in
~/.codex/config.toml for Codex.
git clone https://github.com/mitchtech/agent-warcraft.git
cd agent-warcraft
node scripts/warcraft.mjs doctorUse claude plugin marketplace add /absolute/path/to/agent-warcraft for Claude Code or
codex plugin marketplace add /absolute/path/to/agent-warcraft for Codex, followed by
the same plugin installation command above. claude --plugin-dir /absolute/path/to/agent-warcraft
tries it for one session without installing.
For the agent-warcraft command outside an agent plugin:
npm install -g github:mitchtech/agent-warcraft
agent-warcraft doctor
agent-warcraft play approval_required --session my-session --tool Bash
agent-warcraft preview orc-work-completeAll commands also work as node /path/to/agent-warcraft/scripts/warcraft.mjs ....
Standalone play and preview wait for the short clip; native hooks dispatch
playback to a detached worker so the agent can continue immediately.
Two native custom pets for Codex desktop and Codex CLI: the orc Peon and the human Peasant. Each has nine animations and sixteen look directions. Codex animates them from its own activity: they work while the agent works, wait when it needs you, and slump when something fails. Pets and sounds are independent; install either pet, both, or neither, with either faction's voice.
Without Node.js, from the latest release:
# Peon
curl -LO https://github.com/mitchtech/agent-warcraft/releases/latest/download/agent-warcraft-pet.zip
unzip agent-warcraft-pet.zip -d ~/.codex/pets
# Peasant
curl -LO https://github.com/mitchtech/agent-warcraft/releases/latest/download/agent-warcraft-peasant-pet.zip
unzip agent-warcraft-peasant-pet.zip -d ~/.codex/petsWith the standalone command, or from a checkout with node scripts/warcraft.mjs:
agent-warcraft pet install # Peon
agent-warcraft pet install peasant # Peasant
agent-warcraft doctor --pet peasantThen refresh the Codex desktop pet picker, or enter /pets Peon or
/pets Peasant in a graphics-capable Codex CLI terminal. With CODEX_HOME
set, use $CODEX_HOME/pets instead. Installation leaves pet selection and
sound configuration unchanged; --replace keeps a backup of a different
existing pet. pet status and pet uninstall take the same optional name and
default to the Peon.
Creating a ChatGPT/Codex web pet instead? Upload the nine-row Peon atlas or Peasant atlas and keep the CC BY 4.0 credit. See the Peon guide and the Peasant guide for compatibility, the web upload, backups, and provenance.
Each event lists the Horde line first, then the Alliance line.
| Shared event | When | Horde / Alliance | Default |
|---|---|---|---|
session_started |
A session starts, resumes, or clears | "Ready to work." / "Ready to work." | On |
prompt_submitted |
You send a prompt | "I can do that." "Be happy to." "Work, work." "Okey dokey." / "Right-o." "Yes, me lord." "All right." "Off I go, then!" | On |
annoyed |
Your third prompt inside ten seconds | "Whaaat?" "Me busy. Leave me alone!" "No time for play." "Me not that kind of orc!" / "I didn't vote for you." "We found a witch!" "I'm being repressed!" "A horse kicked me once." | On |
approval_required |
A tool needs permission | "What you want?" "Yes?" / "Yes, milord?" | On |
| Approval for shell commands or file edits | "Hmmm?" / "What?" | On | |
| Approval for a destructive command | "We're under attack!" "Our town is under attack!" / "Our forces are under attack!" "Our town is under siege." | On | |
input_required |
The agent asks you a question | "Hmmm?" / "What?" | On where available |
ready_for_input |
Claude Code is idle and waiting | "Something need doing?" / "More work?" | On for Claude |
turn_completed |
The agent finishes responding | "Work complete!" / "Job's done!" | On |
out_of_gold |
Rate limit, billing error, account on hold, or budget spent | "We need more gold!" / "More gold is required." | On for Claude |
gold_low |
The gold meter crosses its threshold | "Our gold mine is running low." | On with the meter |
out_of_lumber |
A reply hits the output token limit | "We need more lumber." / "More lumber is required." | On for Claude |
out_of_food |
The food meter (context window) crosses its threshold | "Build more burrows!" / "Build more farms." | On with the meter |
error |
Claude Code stops on any other API error | "Our hero has been slain!" / "Our hero has fallen." | Off |
tool_failed |
A tool call fails | "Can't build there." / "I can't build there." | Off |
subagent_started |
A subagent starts work | "Zug zug." "Dabu." "Lok'tar." / "Aye, my lord." "On my way." "Of course." | Off |
context_compacting |
Context is about to be compacted | "Inventory is full." | Off |
session_ended |
A session ends | The peon's death grunt / a weary peasant groan | Off |
| Easter egg | "For the Horde!" "My life for the Horde!" "Why not?" / "For Lordaeron!" "Ready for action." | 2% of session, prompt, ready, and completion cues |
turn_completed is on by default here, unlike the siblings: "Work complete" is
the line people install this for. agent-warcraft preset attention turns it off.
Sound notes explain why each event plays what it plays, how the faction modes divide the lines, and which other lines are worth trying.
Destructive commands are recognized from the approval request's command:
rm with recursive and force flags, git push --force or -f (not
--force-with-lease), git reset --hard, git clean -f, DROP TABLE/DATABASE/SCHEMA,
TRUNCATE TABLE, mkfs, dd of=, chmod -R 777, Remove-Item -Recurse -Force,
and rmdir /s. The alarm is a louder cue, not a safety check: it never blocks,
approves, or logs the command. Only a yes/no flag leaves the hook process.
Annoyed lines replace the third and later prompts sent within ten seconds
in the same session, like clicking a WC3 unit repeatedly. Only timestamps are
stored, never prompt text. Turn them off with agent-warcraft mute annoyed.
Easter eggs never replace approval, question, error, or destructive-command
cues. Turn them off with agent-warcraft mute easter-egg.
Subagent completion is silent. Idle/input notifications and completion events are distinct; event availability depends on the host. See compatibility.
agent-warcraft faction horde # orc peon and advisor (default)
agent-warcraft faction alliance # human peasant, footman, and knight
agent-warcraft faction both # mix every line
agent-warcraft faction random # one faction per session, like a Random player
agent-warcraft faction duo # the Peon works, the Alliance reportsrandom keeps the same faction for a whole session and picks again for the
next. duo splits each event between the factions: the Peon handles the work
chatter (session start, prompts, annoyed lines, subagents, tool failures, and
session end), while the Alliance answers approvals and questions, announces
"Job's done!", and raises the gold, lumber, and food alarms.
Every default cue has lines for both factions, so switching never silences an event. Custom clip lists you write in the configuration are filtered the same way; a list with no clips from the selected faction plays as written.
Claude Code's StopFailure hook reports why a turn failed. Agent Warcraft maps
rate_limit, billing_error, and account_on_hold to out_of_gold,
max_output_tokens to out_of_lumber, and anything else to error. A
quota_auto_resume_disabled notification also plays out_of_gold.
For a warning before the gold runs out, add the meter to your status line. It
prints how much of your tightest limit is left and plays "Our gold mine is
running low." once per session when it crosses gold.lowPercent (80% used by
default), then "We need more gold!" at 100%. The status line runs outside the
plugin, so it needs the standalone command
(npm install -g github:mitchtech/agent-warcraft):
{ "statusLine": { "type": "command", "command": "agent-warcraft statusline" } }⛏ 18% gold (5h) low · 42/100 food
The food meter shows how much of the context window is in use, against
Warcraft III's 100 food cap. When it crosses food.lowPercent (85% by default)
it plays "Build more burrows!" or "Build more farms." (out_of_food) once,
until the context drops back below the threshold, as after a compaction.
The meter reads Claude Code's 5-hour, 7-day, and spend-limit percentages when
your plan reports them. Set gold.budgetUsd to also count a per-session dollar
budget against cost.total_cost_usd. To keep an existing status line, call
the meter from your own script; see budget and status line.
Codex and Gemini have no equivalent hook; scripts there can run
agent-warcraft play out_of_gold.
agent-warcraft status
agent-warcraft faction alliance
agent-warcraft mute prompt_submitted
agent-warcraft unmute prompt_submitted
agent-warcraft mute annoyed
agent-warcraft mute easter-egg
agent-warcraft unmute subagent_started
agent-warcraft mute all
agent-warcraft unmute all
agent-warcraft preset attention
agent-warcraft preset default
agent-warcraft list
agent-warcraft config --effectiveChanges persist immediately and apply to the next hook, without restarting. Global mute/unmute preserves individual event preferences.
- The attention preset keeps the approval, question, ready, and usage
alarms (
out_of_gold,gold_low,out_of_lumber,out_of_food). It turns off session, prompt, annoyed, completion, error, tool-failure, subagent, compaction, and session-end cues. - The default preset restores event enablement. It leaves your custom clips, faction, audio directory, easter-egg setting, and global mute preference unchanged.
The bundled warcraft-control skill also handles requests such as "mute the
peon", "switch to Alliance", "turn off the annoyed lines", or "set up the gold
meter", "Random faction", or "duo mode" inside supported agents. It uses the bundled CLI, so no global npm
installation is needed. status --json and list --json provide structured
output. Status shows when AGENT_WARCRAFT_MUTE overrides the saved global mute
setting.
Configuration stays outside plugin caches, so updates preserve your settings:
- macOS/Linux:
~/.config/agent-warcraft/config.json, or$XDG_CONFIG_HOME/agent-warcraft/config.json. - Windows:
%APPDATA%/agent-warcraft/config.json.
Create the parent directory and save the settings you want to override:
{
"muted": false,
"audioDir": "./audio",
"cooldownMs": 1000,
"faction": "both",
"gold": { "budgetUsd": 20, "lowPercent": 75 },
"food": { "lowPercent": 90 },
"easterEgg": { "chance": 0.05, "clips": ["orc-zug-zug"] },
"events": {
"session_started": { "clips": ["orc-ready"] },
"approval_required": { "clips": ["orc-what-you-want"], "changeClips": ["orc-hmm"], "dangerClips": ["orc-town-under-attack"] },
"subagent_started": { "enabled": true },
"context_compacting": { "enabled": true }
}
}Omit audioDir to use bundled clips. Relative directories resolve from the
configuration file's directory. Custom audio directories must contain a
<clip>.wav for every name in agent-warcraft list; use 16-bit PCM WAV for
compatibility with all players. Copy the clips to your own directory before
replacing them. Installed plugin files can be overwritten by updates.
How clip settings work:
- An event's
clipsarray selects one sound at random, after the faction filter. Use one entry for a fixed sound. changeClipsapplies to shell and file-change approvals.dangerClipsapplies to destructive-command approvals and takes priority.easterEgg.chanceis a probability from 0 to 1.gold.budgetUsdisnull(rate limits only) or a positive dollar amount.gold.lowPercentis between 0 and 100.food.lowPercentis the context window use, between 0 and 100, that playsout_of_food.factionishorde,alliance,both,random, orduo.- Each event accepts
enabled: falseto mute it independently.
agent-warcraft config prints the complete default configuration without
writing anything.
| Environment variable | Effect |
|---|---|
AGENT_WARCRAFT_MUTE |
1 mutes; 0 unmutes; overrides muted |
AGENT_WARCRAFT_CONFIG |
Explicit configuration file path |
AGENT_WARCRAFT_AUDIO_DIR |
Overrides the audio directory |
AGENT_WARCRAFT_STATE_DIR |
Overrides the local playback state directory |
Configure environment variables before starting the agent.
Repeats and overlaps are handled like this:
- Repeated events within
cooldownMsfor the same agent, session, and event are suppressed. - A global playback lock drops overlapping clips across sessions.
- Claude's delayed permission notification is suppressed for at least 10 seconds after a matching approval alert. A permission notification without a preceding alert can still play.
State contains hashed event and session identifiers with timestamps or gold and food levels only. Inactive records are cleaned up after a day, when another sound plays.
Call the shared interface when your agent emits an attention event:
agent-warcraft play session_started --session example
agent-warcraft play prompt_submitted --session example
agent-warcraft play approval_required --session example --tool Bash --command "rm -rf build"
agent-warcraft play turn_completed --session example
agent-warcraft play out_of_gold --session exampleEvery event honors its configuration toggle. Integration scripts should treat playback failures as advisory. No tool-call or transcript polling is needed.
node scripts/warcraft.mjs doctor
node scripts/warcraft.mjs preview orc-readydoctor reports configuration, paths, player availability, clips, the faction,
enabled events, easter eggs, the gold meter, and the optional pet. doctor --pet checks only the Peon (or doctor --pet peasant, the Peasant) and works without an audio player or valid sound
configuration. These commands operate without playing anything.
preview plays a clip even when muted and bypasses event cooldown, but still
respects overlap prevention. A busy player is reported explicitly instead of
silently skipping the preview. Neither command changes settings.
Native hooks exit successfully on malformed input, invalid configuration, missing
audio/player, or playback failure. They produce no prose or permission decisions.
Codex Stop and every Gemini hook emit only {} as neutral JSON required by
those hosts. The status-line meter always prints a line, falling back to a bare
⛏. Run diagnostics when sounds are missing, and check Node's availability and
hook trust settings.
SSH, containers, WSL, and cloud sessions play on the machine executing the hook. An audio bridge must already exist if you expect those sounds on another machine. GitHub marketplace installation is the distribution path; this hook plugin is not submitted to OpenAI's public plugin directory.
npm run check
npm test
npm run test:package
python3 -m pip install -r requirements-dev.txt
python3 scripts/build-audio.py --check
python3 scripts/check-pet.py
python3 scripts/build-assets.py
python3 scripts/package-release.py
npm run siteTests simulate players. They cover:
- host payloads and destructive-command detection
- faction filtering, random and duo modes, the annoyed window, and usage alarms
- the gold and food meters and their once-per-session cues
- easter eggs, configuration, deduplication, and overlap
- failures, paths with spaces, and packaging
CI runs Node 22 and 24 on macOS, Linux, and Windows. See compatibility and release notes.
Python/Pillow are development tools for audio provenance, asset validation, and
previews, not runtime dependencies. build-audio.py rebuilds the clips from
their recorded sources with ffmpeg; --check verifies the
committed files offline. See distribution maintenance
for releases and the site, and contributor instructions for
the project workflow.
- Author: Michael J. Mitchell / mitchtech.
- Warcraft III: Reign of Chaos (2002): Blizzard Entertainment. Warcraft is a trademark of Blizzard Entertainment.
- Clip sources: warcraft.wiki.gg file pages and The Sounds Resource Warcraft III archives.
- Peon and Peasant pet artwork: Michael J. Mitchell / mitchtech, made with Codex image generation, CC BY 4.0 (Peon, Peasant). No game sprites were extracted.
- Sibling projects: Agent Navi, Agent Johnny 5, Agent Rocky, Agent Star Wars, and Agent StarCraft.
- Original plugin inspiration: thephw/claude-meseeks. The peon-in-your-terminal idea owes a nod to peon-ping.
Code and configuration: MIT. Contributor rights in the pet artwork: CC BY 4.0, with provenance and credit for the Peon and the Peasant. Bundled audio is excluded from both licenses; see the audio rights notice. Third-party character rights and trademarks remain with their owners. This is a fan project, not affiliated with or endorsed by Blizzard Entertainment.
















