claude-code-rts-sounds

RTS Sounds for Claude Code

Warcraft Peon, StarCraft SCV, and Star Trek TNG sound effects for Claude Code sessions. Each event randomly picks from all three universes (or lock in a single pack). Fully configurable -- volume, pack selection, per-event toggles, headphones-only mode, and more.

Inspired by this tweet.

Sound Map

Event	Peon	SCV	Star Trek
Session Start	"Something need doing?"	"SCV ready, sir"	TNG communicator chirp
Prompt Submit	"Work work" / "Yes me lord"	"Yes sir" / "Roger"	LCARS beep
Notification	"Huh?" / "What?"	"Go ahead" / "What you want?"	Hailing beep / Alert
Task Complete	"Job's done!"	"SCV reporting"	"Program complete"
Tool Failure	angry peon grumbling	"Not enough minerals"	Error tone

Install as Plugin

# Add as a marketplace (once)
/plugin marketplace add boldflight/claude-code-rts-sounds

# Install
/plugin install rts-sounds@claude-code-rts-sounds

Or test locally:

git clone https://github.com/boldflight/claude-code-rts-sounds.git
claude --plugin-dir ./claude-code-rts-sounds

Install Manually

If you prefer not to use the plugin system, copy the sounds and script to ~/.claude/hooks/ and add the hooks to ~/.claude/settings.json. The hook commands are unchanged from v1:

{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/play.sh ready", "timeout": 5 }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/play.sh yes", "timeout": 5 }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/play.sh what", "timeout": 5 }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/play.sh complete", "timeout": 5 }] }],
    "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/play.sh error", "timeout": 5 }] }]
  }
}

Commands

The plugin provides three slash commands:

Command	Description
/rts-sounds:mute	Mute all sounds (creates ~/.claude/rts-muted)
/rts-sounds:unmute	Unmute sounds (removes ~/.claude/rts-muted)
/rts-sounds:config	View or change settings -- volume, pack, toggles, etc.

Configuration

All settings live in ~/.claude/rts-sounds.json. The file is optional -- defaults apply if missing. All changes take effect immediately, no restart needed.

Default config

{
  "volume": 0.7,
  "pack": "mixed",
  "headphones_only": false,
  "use_sound_effects_device": false,
  "categories": {
    "ready": true,
    "yes": true,
    "what": true,
    "complete": true,
    "error": true
  }
}

Settings reference

Volume (volume: 0.0--1.0, default 0.7) Controls playback volume on all platforms. 0.0 is silent, 1.0 is full volume.

Pack selection (pack: "mixed" | "peon" | "scv" | "trek", default "mixed") Which sound universe to draw from. "mixed" picks randomly across all installed packs. Set to a single pack name to hear only that universe.

Headphones-only mode (headphones_only: true | false, default false) macOS only. When enabled, sounds are suppressed if the default audio output is the built-in speaker. Useful in shared spaces -- sounds play only when headphones or an external audio device are connected.

Per-category toggles (categories) Disable individual event types by setting them to false:

• ready -- session start
• yes -- prompt submitted
• what -- notification
• complete -- task done
• error -- tool failure

Sound Effects device routing (use_sound_effects_device: true | false, default false) macOS only. Routes playback through the macOS Sound Effects output device instead of the default output. This lets you keep notification sounds on a separate device from music or calls.

Mute For a quick global mute that works across all sessions (including background agents):

# Mute
touch ~/.claude/rts-muted

# Unmute
rm ~/.claude/rts-muted

This is the same mechanism the /rts-sounds:mute and /rts-sounds:unmute commands use. Takes effect immediately.

Features

• No-repeat -- When multiple sounds exist for an event, the same sound never plays twice in a row.
• Spam detection -- Three or more rapid prompts within 10 seconds triggers annoyed/exasperated sounds instead of the normal acknowledgements.

Add Your Own Sounds

Sound packs are driven by manifest.json files. To create a new pack:

1. Create a directory under sounds/ (e.g., sounds/zerg/)
2. Drop your .wav files into it
3. Add a manifest.json mapping categories to filenames

Example manifest.json: