https://github.com/al3xjohnson/herald
Audio notifications for Claude Code - TTS summaries or alert sounds
https://github.com/al3xjohnson/herald
claude-code claude-code-plugin claude-code-plugins notifications text-to-speech tts
Last synced: about 21 hours ago
JSON representation
Audio notifications for Claude Code - TTS summaries or alert sounds
- Host: GitHub
- URL: https://github.com/al3xjohnson/herald
- Owner: al3xjohnson
- License: mit
- Created: 2025-12-22T18:20:09.000Z (23 days ago)
- Default Branch: main
- Last Pushed: 2025-12-24T21:05:53.000Z (21 days ago)
- Last Synced: 2025-12-25T10:48:36.104Z (20 days ago)
- Topics: claude-code, claude-code-plugin, claude-code-plugins, notifications, text-to-speech, tts
- Language: TypeScript
- Homepage:
- Size: 1.85 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
Herald
Configurable notifications for Claude Code
TTS or alert sounds — you choose.
---
## Features
- **Text-to-Speech** — Hear a summary of Claude's response when it finishes
- **Alert Sounds** — Play a sound and bring your editor/terminal to focus
- **Cross-Platform** — Works on macOS and Windows
- **Swappable TTS Providers** — Built-in macOS/Windows speech, or use ElevenLabs for premium voices
## Installation
### From Marketplace
```
/plugin install al3xjohnson/agora/herald
```
### Standalone
```
/plugin install al3xjohnson/herald
```
Then configure your preferred notification style:
```
/herald:style tts
```
## Commands
| Command | Description |
|---------|-------------|
| `/herald:enable` | Enable notifications |
| `/herald:disable` | Disable notifications |
| `/herald:status` | Show current configuration |
| `/herald:style ` | Set notification style |
| `/herald:preferences` | Configure TTS settings (max words, custom prompts, editor activation) |
| `/herald:tts` | Configure TTS provider |
## Notification Styles
- **`tts`** — Text-to-speech reads a summary of the response, then activates your window
- **`alerts`** — Plays a sound and activates your window
Both modes automatically detect where Claude Code is running and activate the correct app:
- **VS Code** — When running in the integrated terminal
- **Ghostty, iTerm, Terminal.app, Alacritty, Kitty, WezTerm, Hyper** — When running in a terminal
- **Windows Terminal** — Detected via `WT_SESSION`
Disable window activation with `/herald:preferences activate_editor off`.
Use `/herald:disable` to turn off notifications entirely.
## TTS Providers
| Provider | Platform | Setup |
|----------|----------|-------|
| `macos` | macOS | Built-in, no setup needed |
| `windows` | Windows | Built-in, no setup needed |
| `elevenlabs` | Any | Requires API key and voice ID |
### Using ElevenLabs
```bash
/herald:tts provider elevenlabs
/herald:tts elevenlabs api_key YOUR_API_KEY
/herald:tts elevenlabs voice_id YOUR_VOICE_ID
```
## Configuration
Herald stores its configuration in `~/.config/herald/config.json`:
```jsonc
{
"enabled": true, // true | false
"style": "tts", // "tts" | "alerts"
"tts": {
"provider": "macos", // "macos" | "windows" | "elevenlabs"
"elevenlabs": { // required if provider is "elevenlabs"
"apiKey": "sk-...",
"voiceId": "voice-id"
}
},
"preferences": {
"max_words": 50, // number
"summary_prompt": null, // string | null (custom TTS prompt)
"activate_editor": true // true | false
}
}
```
## Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:
- Development setup
- Code quality standards
- Testing requirements
- Pull request process
## Security
For security concerns, please review [SECURITY.md](SECURITY.md) for:
- Reporting vulnerabilities
- Security best practices
- Supported versions
## License
MIT