{"id":34519644,"url":"https://github.com/al3xjohnson/herald","last_synced_at":"2026-01-13T23:43:21.997Z","repository":{"id":330201298,"uuid":"1121282061","full_name":"al3xjohnson/herald","owner":"al3xjohnson","description":"Audio notifications for Claude Code - TTS summaries or alert sounds","archived":false,"fork":false,"pushed_at":"2025-12-24T21:05:53.000Z","size":1935,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-25T10:48:36.104Z","etag":null,"topics":["claude-code","claude-code-plugin","claude-code-plugins","notifications","text-to-speech","tts"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/al3xjohnson.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-22T18:20:09.000Z","updated_at":"2025-12-24T21:05:41.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/al3xjohnson/herald","commit_stats":null,"previous_names":["get-cubed/herald"],"tags_count":22,"template":false,"template_full_name":null,"purl":"pkg:github/al3xjohnson/herald","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al3xjohnson%2Fherald","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al3xjohnson%2Fherald/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al3xjohnson%2Fherald/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al3xjohnson%2Fherald/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/al3xjohnson","download_url":"https://codeload.github.com/al3xjohnson/herald/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/al3xjohnson%2Fherald/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28399748,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"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","claude-code-plugin","claude-code-plugins","notifications","text-to-speech","tts"],"created_at":"2025-12-24T04:36:57.255Z","updated_at":"2026-01-13T23:43:21.992Z","avatar_url":"https://github.com/al3xjohnson.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/images/icon.png\" alt=\"Herald\" width=\"128\" height=\"128\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eHerald\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/al3xjohnson/herald/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/al3xjohnson/herald\" alt=\"GitHub release\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/al3xjohnson/herald/actions/workflows/ci.yml\"\u003e\u003cimg src=\"https://github.com/al3xjohnson/herald/workflows/CI/badge.svg\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/al3xjohnson/herald\"\u003e\u003cimg src=\"https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen\" alt=\"Node version\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eConfigurable notifications for Claude Code\u003c/strong\u003e\u003cbr\u003e\n  TTS or alert sounds — you choose.\n\u003c/p\u003e\n\n---\n\n## Features\n\n- **Text-to-Speech** — Hear a summary of Claude's response when it finishes\n- **Alert Sounds** — Play a sound and bring your editor/terminal to focus\n- **Cross-Platform** — Works on macOS and Windows\n- **Swappable TTS Providers** — Built-in macOS/Windows speech, or use ElevenLabs for premium voices\n\n## Installation\n\n### From Marketplace\n\n```\n/plugin install al3xjohnson/agora/herald\n```\n\n### Standalone\n\n```\n/plugin install al3xjohnson/herald\n```\n\nThen configure your preferred notification style:\n\n```\n/herald:style tts\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `/herald:enable` | Enable notifications |\n| `/herald:disable` | Disable notifications |\n| `/herald:status` | Show current configuration |\n| `/herald:style \u003ctts\\|alerts\u003e` | Set notification style |\n| `/herald:preferences` | Configure TTS settings (max words, custom prompts, editor activation) |\n| `/herald:tts` | Configure TTS provider |\n\n## Notification Styles\n\n- **`tts`** — Text-to-speech reads a summary of the response, then activates your window\n- **`alerts`** — Plays a sound and activates your window\n\nBoth modes automatically detect where Claude Code is running and activate the correct app:\n- **VS Code** — When running in the integrated terminal\n- **Ghostty, iTerm, Terminal.app, Alacritty, Kitty, WezTerm, Hyper** — When running in a terminal\n- **Windows Terminal** — Detected via `WT_SESSION`\n\nDisable window activation with `/herald:preferences activate_editor off`.\n\nUse `/herald:disable` to turn off notifications entirely.\n\n## TTS Providers\n\n| Provider | Platform | Setup |\n|----------|----------|-------|\n| `macos` | macOS | Built-in, no setup needed |\n| `windows` | Windows | Built-in, no setup needed |\n| `elevenlabs` | Any | Requires API key and voice ID |\n\n### Using ElevenLabs\n\n```bash\n/herald:tts provider elevenlabs\n/herald:tts elevenlabs api_key YOUR_API_KEY\n/herald:tts elevenlabs voice_id YOUR_VOICE_ID\n```\n\n## Configuration\n\nHerald stores its configuration in `~/.config/herald/config.json`:\n\n```jsonc\n{\n  \"enabled\": true,                    // true | false\n  \"style\": \"tts\",                     // \"tts\" | \"alerts\"\n  \"tts\": {\n    \"provider\": \"macos\",              // \"macos\" | \"windows\" | \"elevenlabs\"\n    \"elevenlabs\": {                   // required if provider is \"elevenlabs\"\n      \"apiKey\": \"sk-...\",\n      \"voiceId\": \"voice-id\"\n    }\n  },\n  \"preferences\": {\n    \"max_words\": 50,                  // number\n    \"summary_prompt\": null,           // string | null (custom TTS prompt)\n    \"activate_editor\": true           // true | false\n  }\n}\n```\n\n## Contributing\n\nContributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on:\n\n- Development setup\n- Code quality standards\n- Testing requirements\n- Pull request process\n\n## Security\n\nFor security concerns, please review [SECURITY.md](SECURITY.md) for:\n\n- Reporting vulnerabilities\n- Security best practices\n- Supported versions\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fal3xjohnson%2Fherald","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fal3xjohnson%2Fherald","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fal3xjohnson%2Fherald/lists"}