Claudecraft is a command-line interface (CLI) tool engineered to inject StarCraft sound effects into Claude Code hooks, thereby providing auditory feedback during code execution and interaction. The project leverages npx for easy execution and clack/prompts for interactive user experiences.

The core methodology involves the strategic installation and management of specific "hooks" within the Claude Code environment. These hooks are designed to trigger sound effects at predefined lifecycle events: PreToolUse (before a tool is used), PostToolUse (after a tool is successfully used), and PostToolUseFailure (when a tool use fails). The PostToolUseFailure hook, specifically, is installed when the expanded preset is chosen and utilizes a Bash matcher for event detection.

Sound effects are drawn from curated, race-specific sound pools (Protoss, Terran, Zerg, or a random selection) to introduce variety. These sounds are automatically downloaded from GitHub upon installation if not present locally, residing in a curated-sounds/ directory which is populated from all-sounds/ (source/reference). Users can override the sound directory path via --sounds-dir. To prevent auditory overload, tool sounds (PreToolUse, PostToolUse) default to a 2-second cooldown, configurable via --tool-cooldown. Failure alerts have a default 15-second cooldown, adjustable with --failure-cooldown. Additionally, failure noise filtering is enabled by default, with an option to disable it using --no-failure-filter.

Claudecraft offers flexible configuration via scope:

• Project scope: Writes settings to .claude/settings.local.json within the currently selected project directory.
• Global scope: Writes settings to ~/.claude/settings.json for system-wide application.

The CLI provides a suite of commands for managing these integrations:

• install: Installs StarCraft sound hooks. Supports various options like --scope (project/global), --preset (expanded), --race (protoss, terran, zerg, random), --tool-cooldown, and --yes for non-interactive installation.
• switch: Allows changing race and cooldown settings without a full reinstallation, applicable via --race, --tool-cooldown, and --failure-cooldown flags.
• uninstall: Removes Claudecraft hooks from the environment. Supports --scope (global) and --yes for confirmation bypass. A key feature is the preservation of existing non-Claudecraft hooks, as managed entries are internally tagged for safe removal.
• doctor: Diagnoses the current Claudecraft installation and environment, with an option to output in --json format.
• Interactive mode: Executing npx @wyverselabs/claudecraft without arguments launches an interactive menu with outcome-focused labels.

Local development setup involves bun install and bun run build, followed by direct execution of node dist/cli.js. The bun run curate:tool-sounds command is available for maintainers to rebuild tool sound pools.