boops

🔊 Claude Boops

Sound notifications for Claude Code - Get audio feedback for different interaction events!

🎮 Try the Interactive Demo - Test all sounds and presets in your browser!

⚠️ Warning

This project was entirely vibecoded with Claude and is provided as-is. Use at your own risk!

• All code was generated through conversational AI development with significant human guidance
  • Claude initially couldn't figure out how to make plugins
  • Claude couldn't debug the sound issues independently
  • Claude couldn't work out how to patch the hook messages
  • A human had to guide Claude through these challenges
• Not all code has been fully reviewed by the human - there may be issues that were missed
• No formal testing or QA process
• May contain bugs, security issues, or unexpected behavior
• Modifies your Claude Code settings.json (backups are created)
• Runs a local server on port 8007

If you encounter issues: Check /tmp/claude-sound.log or open an issue on GitHub.

Features

• 🎵 5 Different Sounds for different events (submit, question, permission, success, error)
• ⚡ Dynamic Sound Generation - sounds generated on-the-fly from config.json
• 🎨 Interactive Visual Editor with drag-to-edit interface (optional)
• 📊 Logarithmic Frequency Control for better precision
• 🔒 Directional Drag Locking prevents accidental changes
• 💾 Auto-save changes persist automatically
• 🎧 Custom Sound Files - optionally use your own audio files
• 🧠 Smart Detection - different sounds for success vs error completions, skips redundant sounds

Quick Start

Recommended: Full Setup with Hide-Hooks

For the best experience, install both boops (sound feedback) and hide-hooks (clean up hook messages):

# Add the marketplace
claude plugin marketplace add towc/claude-marketplace

# Install boops for sound feedback
claude plugin install boops

# Install hide-hooks to clean up "hook succeeded" messages
claude plugin install hide-hooks

# After Claude restarts, apply the hide-hooks patch
/hide-hooks:patch

# Restart Claude one more time to see the changes

Why hide-hooks? The boops plugin uses hooks which generate "hook succeeded: Success" messages in the terminal. These messages clutter your screen and can be distracting. The hide-hooks plugin removes these messages while keeping the sound feedback working perfectly.

Just Boops (Not Recommended)

If you only want sound feedback without hiding hook messages:

claude plugin marketplace add towc/claude-marketplace
claude plugin install boops
# Restart Claude - sounds will play but you'll see hook messages

Commands

Once installed, you have access to these slash commands:

• /boops:settings - Open the visual sound editor
• /boops:stop - Stop the sound editor server

Companion Plugins

hide-hooks (Strongly Recommended)

Since boops uses hooks, you'll see "hook succeeded: Success" messages every time you interact with Claude. These messages are verbose and distracting.

Solution: Install hide-hooks to remove these messages while keeping your sound feedback working perfectly.

See the Quick Start section above for the complete installation commands.

Sounds

Event	Config ID	Description
User Submit	user-submit	When you press enter
Permission Needed	permission-needed	When permission prompts appear
Question	question	Multiple choice questions
Success	completion-success	Normal completions (skipped if a question was asked)
Error	completion-error	Errors/failures

Customizing Sounds

Sounds are generated dynamically from config.json - changes take effect immediately after restarting Claude Code!

Option 1: Edit config.json Directly

Edit config.json in the plugin directory. Each sound has:

• tones: Array of tone objects with freq (Hz), duration (seconds), volume (0-1), and silent (boolean)
• filepath (optional): Path to a custom sound file to use instead of generating tones

Example with custom file:

{
  "user-submit": {
    "name": "User Submit",
    "description": "When you press enter",
    "filepath": "/path/to/my-sound.wav"
  }
}

Example with generated tones:

{
  "user-submit": {
    "name": "User Submit",
    "description": "When you press enter",
    "tones": [
      { "freq": 340, "duration": 0.09, "volume": 0.25, "silent": false }
    ]
  }
}

Option 2: Visual Editor (Optional)

Use the interactive visual editor to design sounds:

If installed as a plugin: Type /boops:settings in Claude Code to launch the editor

If installed manually: Run ~/.claude/boops/settings.sh

This will:

1. Start the sound server
2. Open the editor in your browser