{"id":37711902,"url":"https://github.com/dongzhenye/claude-code-notifications","last_synced_at":"2026-01-16T13:20:05.051Z","repository":{"id":304758083,"uuid":"1019079785","full_name":"dongzhenye/claude-code-notifications","owner":"dongzhenye","description":"🔔 Never miss Claude's response\\! Notification solutions for Claude Code - from terminal bells to desktop alerts.","archived":false,"fork":false,"pushed_at":"2025-08-20T17:11:53.000Z","size":301,"stargazers_count":8,"open_issues_count":3,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-13T07:13:26.149Z","etag":null,"topics":["claude-code","developer-tools","productivity","sound-notifications","terminal-notification"],"latest_commit_sha":null,"homepage":"https://claude-code-notifications.vercel.app","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dongzhenye.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-13T17:33:57.000Z","updated_at":"2025-08-27T03:33:49.000Z","dependencies_parsed_at":"2025-07-15T05:41:44.003Z","dependency_job_id":"3e284dc1-868d-4079-adf9-fba29519f84a","html_url":"https://github.com/dongzhenye/claude-code-notifications","commit_stats":null,"previous_names":["dongzhenye/claude-code-sound-notifications","dongzhenye/claude-code-notifications"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/dongzhenye/claude-code-notifications","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dongzhenye%2Fclaude-code-notifications","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dongzhenye%2Fclaude-code-notifications/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dongzhenye%2Fclaude-code-notifications/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dongzhenye%2Fclaude-code-notifications/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dongzhenye","download_url":"https://codeload.github.com/dongzhenye/claude-code-notifications/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dongzhenye%2Fclaude-code-notifications/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","developer-tools","productivity","sound-notifications","terminal-notification"],"created_at":"2026-01-16T13:20:04.303Z","updated_at":"2026-01-16T13:20:05.029Z","avatar_url":"https://github.com/dongzhenye.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔔 Claude Code Notifications\n\n\u003cdiv align=\"center\"\u003e\n  \n  **Never miss Claude's response again**\n  \n  [![GitHub stars](https://img.shields.io/github/stars/dongzhenye/claude-code-notifications?style=flat-square)](https://github.com/dongzhenye/claude-code-notifications/stargazers)\n  [![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n  [![Platform](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-lightgrey?style=flat-square)](https://github.com/dongzhenye/claude-code-notifications)\n  \n  *Elegant notification solutions for Claude Code CLI - from simple terminal bells to rich desktop alerts*\n  \n  [Quick Start](#-quick-start) • [Installation](#-installation) • [Configuration](#-configuration) • [Examples](#-examples)\n\n\u003c/div\u003e\n\n---\n\n## ✨ The Problem We Solve\n\nEver found yourself:\n- 🤔 **Constantly switching tabs** to check if Claude has responded?\n- 😔 **Missing Claude's questions** while working in another window?\n- ⏰ **Wasting time** waiting when Claude has already finished?\n\n**We've got you covered!** Choose from three notification styles that fit your workflow perfectly.\n\n## 🎯 Choose Your Style\n\n![Choose Your Notification Style](assets/tiers-desktop.jpeg)\n\n\u003cdiv align=\"center\"\u003e\n  \n  **[Minimal](#-minimal--built-in-simplicity)** • **[Recommended](#-recommended--perfect-balance)** • **[Custom](#-custom--unlimited-possibilities)**\n  \n\u003c/div\u003e\n\n## 🚀 Quick Start\n\n**Most users should use the Recommended tier:**\n\n```bash\n# One-line installation (works anywhere - downloads configs automatically)\ncurl -sSL https://raw.githubusercontent.com/dongzhenye/claude-code-notifications/main/install.sh | bash\n```\n\nThat's it! You now have smart audio notifications configured. 🎉\n\n## 📋 Installation\n\n### Prerequisites\n\n- **Claude Code CLI** installed (`claude` command available)\n- **macOS / Linux / Windows** operating system\n- **Audio output** for sound notifications\n\n### Installation Options\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🎯 Option 1: Automatic Installation (Recommended)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Download and run the installer\ncurl -sSL https://raw.githubusercontent.com/dongzhenye/claude-code-notifications/main/install.sh | bash\n```\n\nOr clone and run locally:\n\n```bash\ngit clone https://github.com/dongzhenye/claude-code-notifications.git\ncd claude-code-notifications\n./install.sh\n```\n\nThe installer will:\n- ✅ Detect your operating system\n- ✅ Automatically download configurations from GitHub (no cloning needed!)\n- ✅ Apply the recommended configuration\n- ✅ Create a backup of existing settings\n- ✅ Provide desktop notification setup options\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⚙️ Option 2: Manual Installation\u003c/b\u003e\u003c/summary\u003e\n\n1. **Choose your configuration file:**\n   - macOS: `recommended/recommended.macos.json`\n   - Linux: `recommended/recommended.linux.json`\n   - Windows: `recommended/recommended.windows.json`\n\n2. **Copy to Claude settings:**\n   ```bash\n   cp recommended/recommended.macos.json ~/.claude/settings.json\n   ```\n\n3. **Test the configuration:**\n   ```bash\n   # macOS\n   afplay /System/Library/Sounds/Glass.aiff\n   \n   # Linux\n   paplay /usr/share/sounds/freedesktop/stereo/message.oga\n   \n   # Windows (PowerShell)\n   [System.Media.SystemSounds]::Asterisk.Play()\n   ```\n\n\u003c/details\u003e\n\n## 🎨 Configuration\n\n### 🔵 Minimal — Built-in Simplicity\n\n**Perfect for:** Users who want instant notifications with zero setup.\n\n```bash\nclaude config set --global preferredNotifChannel terminal_bell\n```\n\n**Features:**\n- ✅ **5-second setup** - Just run one command\n- ✅ **Works everywhere** - Universal terminal bell\n- ✅ **Zero dependencies** - Nothing to install\n- ❌ **Same sound for all** - No event differentiation\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003emacOS Terminal Sound Setup\u003c/b\u003e\u003c/summary\u003e\n\nIf you don't hear the bell on macOS:\n1. Open **Terminal → Preferences → Profiles**\n2. Select your profile → **Advanced** tab\n3. Enable **\"Audible bell\"**\n4. Adjust volume in **System Preferences → Sound**\n\n\u003c/details\u003e\n\n### ⭐ Recommended — Perfect Balance\n\n**Perfect for:** Daily users who want smart notifications without fatigue.\n\n**What makes it special:**\n- 🎵 **Only 2 key events** - Needs input \u0026 task complete\n- 🎶 **Carefully chosen sounds** - Glass (attention) \u0026 Tink (done)\n- 😌 **No notification fatigue** - Designed for all-day use\n- 🌍 **Cross-platform** - Works on all operating systems\n\n**Sound Philosophy:**\n```\nHigh-frequency events (completion) → Gentle sound (Tink)\nLow-frequency events (needs input) → Noticeable sound (Glass)\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eConfiguration Details\u003c/b\u003e\u003c/summary\u003e\n\nThe configuration maps Claude events to system sounds:\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [{\n      \"description\": \"Sound notification on completion\",\n      \"hooks\": [{\n        \"type\": \"sound\",\n        \"path\": \"/System/Library/Sounds/Tink.aiff\"\n      }]\n    }],\n    \"Notification\": [{\n      \"description\": \"Sound notification when input needed\",\n      \"hooks\": [{\n        \"type\": \"sound\",\n        \"path\": \"/System/Library/Sounds/Glass.aiff\"\n      }]\n    }]\n  }\n}\n```\n\n\u003c/details\u003e\n\n### 🚀 Custom — Unlimited Possibilities\n\n**Perfect for:** Power users who want visual notifications and advanced integrations.\n\n**Examples included:**\n- 🖥️ **Desktop notifications** with title and message\n- 📱 **Push notifications** to your phone\n- 🌐 **Webhook integrations** with Slack/Discord\n- 🎨 **Custom scripts** for any behavior\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eDesktop Notification Example (macOS)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Install terminal-notifier (if needed)\nbrew install terminal-notifier\n\n# Use the provided script\ncp custom/system-notify.macos.sh ~/claude-code-notifications/\n\n# Configure in ~/.claude/settings.json\n{\n  \"hooks\": {\n    \"Notification\": [{\n      \"hooks\": [{\n        \"type\": \"command\",\n        \"command\": \"~/claude-code-notifications/custom/system-notify.macos.sh notification\"\n      }]\n    }]\n  }\n}\n```\n\nThe script provides:\n- 🔔 System notification center integration\n- 📝 Custom titles and messages\n- 🎵 Optional sound effects\n- 🖼️ Claude icon in notifications\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCreate Your Own Integration\u003c/b\u003e\u003c/summary\u003e\n\nCreate a custom script that receives the event type as first argument:\n\n```bash\n#!/bin/bash\nEVENT_TYPE=$1\n\ncase \"$EVENT_TYPE\" in\n  \"notification\")\n    # Your code for input needed\n    curl -X POST https://your-webhook.com/claude-needs-input\n    ;;\n  \"stop\")\n    # Your code for task complete\n    osascript -e 'display notification \"Task complete!\" with title \"Claude\"'\n    ;;\nesac\n```\n\nEndless possibilities:\n- 🏠 Smart home integration (turn on a light)\n- 📊 Log events to a database\n- 🤖 Trigger other automations\n- 📈 Track productivity metrics\n\n\u003c/details\u003e\n\n## 🧪 Testing \u0026 Debugging\n\n### Test System Sounds\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🍎 macOS\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Test individual sounds\nafplay /System/Library/Sounds/Glass.aiff\nafplay /System/Library/Sounds/Tink.aiff\n\n# Explore all available sounds\nfor sound in Basso Blow Bottle Frog Funk Glass Hero Morse Ping Pop Purr Sosumi Submarine Tink; do \n  echo \"Playing $sound...\"\n  afplay \"/System/Library/Sounds/$sound.aiff\"\n  sleep 1\ndone\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐧 Linux\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Test with PulseAudio\npaplay /usr/share/sounds/freedesktop/stereo/message.oga\n\n# Test with ALSA\naplay /usr/share/sounds/freedesktop/stereo/complete.oga\n\n# List available sounds\nfind /usr/share/sounds -name \"*.oga\" -o -name \"*.wav\"\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🪟 Windows\u003c/b\u003e\u003c/summary\u003e\n\n```powershell\n# Test system sounds\n[System.Media.SystemSounds]::Asterisk.Play()\n[System.Media.SystemSounds]::Exclamation.Play()\n[System.Media.SystemSounds]::Hand.Play()\n\n# List available WAV files\nGet-ChildItem C:\\Windows\\Media\\*.wav | Select-Object Name\n```\n\n\u003c/details\u003e\n\n### Common Issues\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔇 No sound playing?\u003c/b\u003e\u003c/summary\u003e\n\n1. **Check system volume** - Ensure it's not muted\n2. **Test the sound file directly** - Use commands above\n3. **Verify file paths** - Ensure sound files exist\n4. **Check permissions** - Some systems restrict audio playback\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔊 Multiple/duplicate sounds?\u003c/b\u003e\u003c/summary\u003e\n\n1. **Clear terminal bell:**\n   ```bash\n   claude config set --global preferredNotifChannel none\n   ```\n\n2. **Check for duplicate hooks:**\n   ```bash\n   cat ~/.claude/settings.json\n   ```\n\n3. **Use the installer's backup:**\n   ```bash\n   cp ~/.claude/settings.json.backup ~/.claude/settings.json\n   ```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e⚙️ Settings not applying?\u003c/b\u003e\u003c/summary\u003e\n\n- Settings take effect **immediately** (no restart needed)\n- Check JSON syntax with `jq . ~/.claude/settings.json`\n- Ensure you're editing the correct file: `~/.claude/settings.json`\n- Try the automatic installer for proper configuration\n\n\u003c/details\u003e\n\n## 📖 Examples\n\n### Real-world Use Cases\n\n**🎯 Focused Development**\n```bash\n# Start a long-running task\nclaude \"Refactor this entire codebase to use TypeScript\"\n# Switch to email/Slack/browser\n# 🔔 Get notified when Claude needs clarification\n# ✅ Get notified when complete\n```\n\n**📚 Learning \u0026 Exploration**\n```bash\n# Ask complex questions\nclaude \"Explain the entire architecture and create documentation\"\n# Go make coffee ☕\n# 🔔 Return when Claude is ready\n```\n\n**🔄 Iterative Tasks**\n```bash\n# Multi-step processes\nclaude \"1. Analyze code 2. Write tests 3. Fix bugs 4. Update docs\"\n# Work on other things\n# 🔔 Get notified at each step requiring input\n```\n\n## 🛠️ Advanced Configuration\n\n### Claude Event Types\n\nClaude Code supports these notification events:\n\n| Event | Description | Frequency | Recommended Sound |\n|-------|-------------|-----------|-------------------|\n| `Notification` | Needs user input/permission | Low | Noticeable (Glass) |\n| `Stop` | Completed response | High | Gentle (Tink) |\n\n### Hook System\n\nThe Claude Code hook system is powerful and flexible:\n\n```json\n{\n  \"hooks\": {\n    \"EventName\": [{\n      \"description\": \"Human-readable description\",\n      \"hooks\": [{\n        \"type\": \"sound|command\",\n        \"path\": \"/path/to/sound\",\n        \"command\": \"command to run\"\n      }]\n    }]\n  }\n}\n```\n\nMultiple hooks can be chained for complex behaviors.\n\n## 🤝 Contributing\n\nWe love contributions! Here's how you can help:\n\n- 🐛 **Report bugs** - Open an issue with details\n- 💡 **Suggest features** - Share your ideas\n- 🔧 **Submit PRs** - Improvements welcome\n- 📖 **Improve docs** - Help others get started\n- ⭐ **Star the repo** - Show your support\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 👨‍💻 Author\n\nCreated with ❤️ by [Zhenye Dong](https://github.com/dongzhenye)\n\n---\n\n\u003cdiv align=\"center\"\u003e\n  \n  **If this tool saves you time, please consider giving it a ⭐**\n  \n  [Report Bug](https://github.com/dongzhenye/claude-code-notifications/issues) • [Request Feature](https://github.com/dongzhenye/claude-code-notifications/issues)\n  \n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdongzhenye%2Fclaude-code-notifications","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdongzhenye%2Fclaude-code-notifications","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdongzhenye%2Fclaude-code-notifications/lists"}