{
  "markdown": "<div align=\"center\">\n  <img src=\"assets/logo_full.png\" alt=\"tinynudge\" width=\"300\" />\n  <p><strong>A tiny notifier for AI coding agents.</strong></p>\n  <p>Get a banner + sound when your agent finishes a task or pauses for your approval — step away without missing a beat.</p>\n</div>\n\n---\n\n## Supports\n\n| Agent | Status |\n|-------|--------|\n| Claude Code | ✅ |\n| Cursor | ✅ |\n| Gemini CLI | ✅ *(experimental)* |\n| Codex | ✅ *(experimental)* |\n| Any hooks-capable agent | ✅ — point it at `notify.sh` |\n\n**Platforms:** macOS (native banners + click-to-focus) · Linux (PulseAudio / ALSA / libnotify) · Windows (Git Bash / WSL)\n\n## Install\n\n### macOS (recommended)\n\n```bash\nbrew install hiskuDN/tap/tinynudge\ntinynudge-setup\n```\n\n`brew install` gets you the native app. `tinynudge-setup` auto-detects your agents (`~/.claude`, `~/.cursor`) and wires their hooks.\n\n### All platforms / manual\n\n```bash\ngit clone https://github.com/hiskuDN/tinynudge.git\ncd tinynudge\n./install.sh\n```\n\nThe installer auto-detects agents and wires hooks. On macOS it will also prompt you to install the native binary via Homebrew if you haven't already.\n\n## How it works\n\nEach supported agent has a hooks system. `tinynudge` registers these hooks:\n\n| Agent | Event | What happens |\n|-------|-------|--------------|\n| Claude Code | `Stop` | Banner when the turn ends |\n| Claude Code | `PermissionRequest` | Banner when Claude pauses for approval |\n| Cursor | `stop` | Banner when agent turn ends |\n| Gemini CLI | session end | Banner when agent finishes |\n\nThe hook calls `notify.sh <agent> <event>`, which plays a sound and shows a banner via:\n\n1. **macOS** — the native `tinynudge.app` (click-to-focus routes back to your editor)\n2. **Linux** — `paplay` / `aplay` / `notify-send`\n3. **Windows** — `powershell [console]::beep`\n\n### Click-to-focus (macOS)\n\nWhen you click the banner, `tinynudge.app` uses System Events to raise the exact window that triggered the notification — even if you have multiple Cursor or terminal windows open. Supported apps:\n\n- Cursor, VS Code\n- iTerm2, Warp, Ghostty, Terminal.app\n\nIf the target app is already in focus when the notification fires, the banner is suppressed and only the sound plays.\n\n### Immediate focus mode\n\nIf you'd rather have your editor focus automatically — no click needed:\n\n```bash\nexport TINYNUDGE_ACTIVATE_IMMEDIATELY=true\n```\n\nAdd that to your shell profile.\n\n### Voice notifications\n\ntinynudge can speak notifications aloud using [StackVox](https://github.com/StackOneHQ/stackvox), an offline TTS library with ~13 ms latency.\n\n**Setup:**\n\n```bash\npip install stackvox\nstackvox serve   # start the daemon (add to login items or a launch agent)\n```\n\n**Enable in your config** (`~/.tinynudge/config`):\n\n```bash\nTINYNUDGE_VOICE=true\n```\n\nVoice fires only when the banner shows — it's suppressed along with the banner when your editor is already in focus. For permission events, voice says *\"Bash command needs approval\"* or *\"Edit: filename\"* rather than reading the raw command aloud.\n\nOptional tuning (also in `~/.tinynudge/config`):\n\n```bash\nTINYNUDGE_VOICE_NAME=af_heart   # StackVox voice ID\nTINYNUDGE_VOICE_SPEED=1.1       # playback speed (1.0 = normal)\n```\n\n## Sounds\n\n| Event | macOS | Linux | Windows |\n|-------|-------|-------|---------|\n| Agent done | `Glass.aiff` | freedesktop bell | 800 Hz beep |\n| Waiting for approval | `Ping.aiff` | freedesktop bell | 1200 Hz beep |\n\nAny file from `/System/Library/Sounds/` works on macOS: Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink.\n\n## Uninstall\n\n```bash\n./uninstall.sh\n```\n\nRemoves hooks from each agent's config and deletes `~/.tinynudge/`. To also remove the binary: `brew uninstall tinynudge`.\n\n## Manual setup\n\nEvery supported agent just needs a hook that runs `notify.sh <agent-name> <event>`. Example for Codex (or any other hooks-capable agent):\n\n```json\n{\n  \"hooks\": {\n    \"stop\": [\n      {\n        \"type\": \"command\",\n        \"command\": \"$HOME/.tinynudge/notify.sh codex stop\"\n      }\n    ]\n  }\n}\n```\n\n## Development\n\n```bash\n./build.sh            # builds tinynudge.app into build/\n```\n\nThe Swift source lives in `notifier/` — ~200 lines, compiled with `swiftc`. No Xcode, no SPM, no dependencies.\n\n## Credits\n\nClick-routing architecture (process exits after delivery, macOS re-launches on click) is adapted from [`terminal-notifier`](https://github.com/julienXX/terminal-notifier) by Eloy Durán and Julien Blanchard.\n\n## License\n\nMIT\n",
  "bytes": 4478,
  "sha": "116184ae5352b424c59d44063cc6962bbf726da4879455c5b68b1fb4b36e7313",
  "repo_slug": "hiskudn/claude-notify",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hiskudn_claude_notify_claude_notify_8bcf30aa/readme"
}