claudecraft는 Claude Code 환경에 StarCraft 사운드 이펙트를 통합하기 위한 CLI(Command Line Interface) 도구입니다. 이 프로젝트의 핵심 목표는 사용자가 특정 코드 실행 지점에 스타크래프트 효과음을 들을 수 있도록 하여 개발 경험에 재미와 피드백을 추가하는 것입니다.

핵심 방법론은 Claude Code의 '훅(hooks)'에 사운드 트리거를 삽입하는 것입니다. 이 도구는 주로 PreToolUse, PostToolUse, 그리고 expanded 모드에서는 PostToolUseFailure 훅에 사운드 재생 기능을 통합합니다. 특히 PostToolUseFailure 훅은 "Bash matcher"를 사용하여 특정 Bash 명령 실행 또는 스크립트 실행 시점에 실패 사운드를 트리거하도록 설정됩니다.

설치 시 npx @wyverselabs/claudecraft install 명령을 사용하며, --scope 옵션을 통해 사운드 훅이 프로젝트 로컬(project 스코프의 경우 .claude/settings.local.json) 또는 전역(global 스코프의 경우 ~/.claude/settings.json) 설정 파일에 작성될지 지정할 수 있습니다. install 명령은 --race 옵션을 통해 Protoss, Terran, Zerg 또는 Random 종족 테마의 사운드를 선택할 수 있게 하며, PreToolUse와 PostToolUse 훅은 선택된 종족에 특화된 사운드 풀에서 무작위로 사운드를 재생하여 다양성을 제공합니다. 사운드 재생에는 기본적으로 2초의 쿨다운(--tool-cooldown)이 적용되며, 실패 알림에는 15초의 쿨다운(--failure-cooldown)이 적용됩니다. 실패 사운드에 대한 노이즈 필터링은 기본적으로 활성화되어 있습니다.

이 도구는 @clack/prompts 라이브러리를 활용하여 사용자 친화적인 대화형 프롬프트(npx @wyverselabs/claudecraft Interactive)를 제공합니다. 또한, switch 명령을 통해 사운드 재설치 없이 종족이나 쿨다운 설정을 변경할 수 있으며, uninstall 명령으로 설치된 훅을 안전하게 제거합니다. 기존에 설치된 claudecraft와 관련 없는 훅들은 보존되며, claudecraft가 관리하는 엔트리들은 안전한 제거를 위해 태그됩니다. 사운드 파일은 설치 시 GitHub에서 자동으로 다운로드되거나, --sounds-dir 옵션을 통해 로컬 경로를 지정할 수 있습니다. 프로젝트는 Bun과 TypeScript로 빌드되었으며, 테스트 및 유지보수를 위한 명령어도 제공됩니다.