claude-code-audio-hooks

🥈Silver

Claude Code Audio Hooks is an audio notification system for Claude Code that plays sound alerts when Claude finishes responding. It benefits developers and operations teams by providing auditory feedback during multitasking. The tool connects to Claude Code and integrates with CLI tools, enhancing productivity in development and operations workflows.

4630Updated 1mo ago

Intermediate30min to implementautomation

Saves ~15 min per use

Quick InstallView Source

git clone https://github.com/ChanMeng666/claude-code-audio-hooks.git

Works with:

Claude

Overview

About This Skill

echook is an audio notification system designed for Claude Code, Cursor IDE, and Codex CLI that automates sound alerts across 26 hook events including task completion, permission requests, and context changes. The system operates entirely through natural language commands—you tell your AI agent what to do in plain English and it handles installation, configuration, and management automatically. It monitors API quota usage with rate-limit alerts at 80% and 95%, supports two audio themes, includes webhooks and text-to-speech capabilities, and displays a context monitor status line. The tool is machine-operable end-to-end via a JSON CLI with stable error codes, making it ideal for developers and operations teams who need reliable auditory feedback while managing multiple tasks without interrupting their workflow.

How to Use

["Install claude-code-audio-hooks by running `pip install claude-code-audio-hooks` in your terminal. Ensure you have Python 3.8+ installed.","Configure the system by editing the config file at `~/.claude/audio-hooks/config.json`. Set your preferred sound file paths and trigger conditions (e.g., task duration thresholds).","Test the setup by running a sample command like `claude --version` to verify the audio hook triggers correctly for your specified conditions.","Monitor the log file at `~/.claude/audio-hooks/audio-hooks.log` to track triggered events and troubleshoot any issues with sound playback.","Customize further by adding new sound files to the `sounds/` directory or adjusting the Python script in `~/.claude/audio-hooks/hook.py` for advanced use cases."]

Use Cases

Receive audio alerts when Claude Code finishes processing responses

Get notified of API rate-limit warnings at 80% and 95% quota usage

Monitor permission requests and tool usage events in Codex CLI with sound alerts

Track file changes and working directory switches with audio notifications

Setup & Installation

Quick Install

No install command available. Check the GitHub repository for manual installation instructions.

Alternative Install (Git Clone)

git clone https://github.com/ChanMeng666/claude-code-audio-hooks

Requirements

Claude Code or compatible AI agent
Works with: Claude

Quick Start Guide

Install the Skill

Copy the install command above and run it in your terminal.

Open Your AI Agent

Launch Claude Code, Cursor, or your preferred AI coding agent.

Try It Out

Use the prompt template or examples below to test the skill.

Customize

Adapt the skill to your specific use case and workflow.

Usage Examples

Prompt Template

Set up audio notifications for [CLAUDE_CODE_PROJECT_NAME] using claude-code-audio-hooks. Configure the system to play [SOUND_ALERT_NAME] when Claude Code finishes executing [TASK_DESCRIPTION]. Ensure the audio hook triggers only for [SPECIFIC_EVENT_CONDITIONS, e.g., 'long-running tasks exceeding 30 seconds']. Test the setup by running [TEST_COMMAND] and verify the alert plays correctly.

Example Output

The audio notification system has been successfully configured for your 'ecommerce-api' project. I've set up claude-code-audio-hooks to play the 'ding.mp3' sound whenever Claude Code completes a deployment task that involves pushing changes to the staging environment. The system is configured to trigger only for tasks that take longer than 25 seconds to execute, which helps filter out quick linting or formatting runs.

During testing, I executed the command `claude deploy-staging` which triggered a 37-second deployment process. Immediately after the deployment completed, the 'ding.mp3' alert played through your system speakers. The hook also logged the event in your `.claude/audio-hooks.log` file with the timestamp, task duration (37s), and exit code (0).

To customize further, you can adjust the sound file path in `~/.claude/audio-hooks/config.json` or modify the trigger conditions in the `rules` section. The system currently supports MP3, WAV, and system beep sounds, with plans to add text-to-speech alerts in the next update.