Agent Warcraft
300 0 11/16

Sound cues for coding agents

Work complete.Job's done.

Your coding agent, with a peon'speasant's work ethic.

Agent Warcraft plays Warcraft III voice lines when Claude Code, Codex, or Gemini CLI does something you should hear about. You get "Ready to work" at the start, "Work complete" when a turn ends, and "We're under attack!" when an approval is for rm -rf. When your usage runs out, the advisor says what every RTS player already knows: we need more gold.

Local. No telemetry. Never approves or blocks anything.

PeonPeasant

Something need doing?More work?

Click the portrait

Click the portrait. Then keep clicking: the third click inside ten seconds is exactly how the annoyed cue works. The Peon is a bundled Codex pet, acting out each cue.The Peasant is a bundled Codex pet, acting out each cue.
Native hooks forClaude CodeCodexGemini CLIplusYour own agentmacOS · Linux · Windows

Event map

Every cue, wired to an event.

Fifty-eight lines across two factions, each tied to something your agent does. The faction switch at the top picks whose voice you hear, here and in your terminal (agent-warcraft faction both mixes them, random picks one per session, and duo lets the Peon work while the Alliance reports). Click a line to hear it. Your browser stays quiet until you do.

EventWhenLinesDefault
session_startedA session starts, resumes, or clearsOn
prompt_submittedYou send a promptOn
annoyedYour third prompt inside ten secondsOn
approval_requiredA tool needs permissionOn
input_requiredThe agent asks you a questionOn*
ready_for_inputClaude Code is idle and waitingOn*
turn_completedThe agent finishes respondingOn
out_of_goldRate limit, billing, or budget exhaustedOn*
gold_lowThe status line meter crosses its thresholdOn*
out_of_lumberA reply hits the output token limitOn*
out_of_foodThe status line food meter (context window) crosses its thresholdOn*
errorClaude Code stops on another API errorOff
tool_failedA tool call failsOff
subagent_startedA subagent starts workOff
context_compactingContext is about to be compactedOff
session_endedA session endsOff
easter-eggRarely replaces a session, prompt, ready, or completion cue2%

*Event coverage depends on your agent. Off events turn on with agent-warcraft unmute EVENT.

Codex pets

Something need doing?More work?

Two native custom pets for Codex desktop and Codex CLI: the orc Peon and the human Peasant. Each has nine animations, sixteen look directions, and a pickaxe close at hand. 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. Installing a pet never selects it and never touches your sound settings.

Creating a web pet? Download the Peon web atlasDownload the Peasant web atlas for a separate account upload. Upload and attribution guideUpload and attribution guide. Artwork: CC BY 4.0CC BY 4.0.

The Peon is idle
Sixteen look directions

Destructive-command alarm

Our town is under attack.

When an approval is for something you cannot take back, the cue changes. Recursive force deletes, force pushes, hard resets, dropped tables, mkfs, dd, and their PowerShell cousins all sound the alarm instead of the ordinary prompt.

It is a louder cue, not a safety check. The hook never blocks, approves, logs, or stores the command; only a yes/no flag leaves it.

agent wants to run:
$ git push --force origin main
allow? [y/n] 

Usage alarms

We need more gold.

Claude Code reports why a turn failed. Rate limits, billing errors, and accounts on hold play the gold line. Hitting the output token limit plays the lumber line. An optional status-line meter shows how much of your tightest limit is left, and the advisor warns you once when the mine runs low. A food meter beside it tracks the context window and calls for more farms before it fills.

Budget and status line guide
~/project main⛏ 18% gold (5h) low · 42/100 food
  1. rate_limit · billing_error · account_on_holdout_of_gold
  2. max_output_tokensout_of_lumber
  3. status line ≥ 80%gold_low
  4. context window ≥ 85%out_of_food

Install

Two commands. Ready to work.

Run these in your terminal. Sounds need Node.js 22+ and a local audio player; restart your agent after installation. The pet needs neither.

Claude Code

claude plugin marketplace add mitchtech/agent-warcraft
claude plugin install warcraft@agent-warcraft

Codex

codex plugin marketplace add mitchtech/agent-warcraft
codex plugin add warcraft@agent-warcraft

Gemini CLI

gemini extensions install https://github.com/mitchtech/agent-warcraft

Review and trust the sound hooks in Codex's hook settings. Running Agent Navi, Agent Johnny 5, Agent Rocky, Agent Star Wars, or Agent StarCraft too? Enable one per host so a fairy, a robot, a peon, an Eridian, two droids, and an SCV do not talk over each other. Other agents use the standalone event interface.

Pet ZIP, no Node

curl -LO https://github.com/mitchtech/agent-warcraft/releases/latest/download/agent-warcraft-pet.zip
unzip agent-warcraft-pet.zip -d ~/.codex/petscurl -LO https://github.com/mitchtech/agent-warcraft/releases/latest/download/agent-warcraft-peasant-pet.zip
unzip agent-warcraft-peasant-pet.zip -d ~/.codex/pets

Pet installer

npm install -g github:mitchtech/agent-warcraft
agent-warcraft pet install peasant

Showing the PeonPeasant; switch pets above. Then refresh the Codex desktop pet picker, or enter /pets PeonPeasant in a graphics-capable Codex CLI terminal. With CODEX_HOME set, unzip into $CODEX_HOME/pets. The installer keeps a backup with --replace and never selects the pet for you. Peon guide · Peasant guide

Sound controls
agent-warcraft status
agent-warcraft faction alliance
agent-warcraft faction duo
agent-warcraft mute prompt_submitted
agent-warcraft unmute subagent_started
agent-warcraft preset attention
agent-warcraft unmute all

Or ask your agent to "switch the peon to Alliance" or "mute the peon" through the bundled control skill. Global mute preserves your event preferences.

Web pet

Upload the atlas

Codex web takes a nine-row atlas instead of the local bundle. Download the Peon atlas or the Peasant atlas and keep the CC BY 4.0 credit when you share it. An account upload is separate from the local pet.

Compatibility

Where it plays.

Sounds play on the machine that runs the hook, across agents and operating systems.

Full compatibility guide
Sound support by environment
EnvironmentSoundsEvents
Claude CodeNative hooksAll 15, plus the status-line meter
Codex CLI and desktopTrusted hooksSession, prompt, approval, completion, subagent, compaction, end
Gemini CLINative extensionSession, prompt, approval, completion, compaction, end
Other agents / scriptsEvent interfaceWhatever you call
SSH, containers, WSLLocal audio neededSame as the host

Zug zug.Off I go, then.

Keep building. The peonpeasant will tell you when the work is done.

Explore the project