{"id":50539376,"url":"https://github.com/devinosolutions/ai-agent-notifier","last_synced_at":"2026-06-03T19:01:34.958Z","repository":{"id":357955128,"uuid":"1239204116","full_name":"DevinoSolutions/ai-agent-notifier","owner":"DevinoSolutions","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-15T02:03:26.000Z","size":74,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T02:42:35.233Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/DevinoSolutions.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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-14T21:36:46.000Z","updated_at":"2026-05-15T02:03:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/DevinoSolutions/ai-agent-notifier","commit_stats":null,"previous_names":["devinosolutions/ai-agent-notifier"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/DevinoSolutions/ai-agent-notifier","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinoSolutions%2Fai-agent-notifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinoSolutions%2Fai-agent-notifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinoSolutions%2Fai-agent-notifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinoSolutions%2Fai-agent-notifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DevinoSolutions","download_url":"https://codeload.github.com/DevinoSolutions/ai-agent-notifier/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DevinoSolutions%2Fai-agent-notifier/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33876333,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2026-06-03T19:01:34.058Z","updated_at":"2026-06-03T19:01:34.953Z","avatar_url":"https://github.com/DevinoSolutions.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eai-agent-notifier\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eDesktop \u0026 phone notifications for AI coding agents\u003c/strong\u003e\u003cbr /\u003e\n  One tool. One config. Every agent. Never miss when your AI finishes or needs input.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/icons/claude.png\" alt=\"Claude Code\" width=\"36\" /\u003e\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"assets/icons/codex.png\" alt=\"Codex CLI\" width=\"36\" /\u003e\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"assets/icons/cursor.png\" alt=\"Cursor\" width=\"36\" /\u003e\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"assets/icons/gemini.png\" alt=\"Gemini CLI\" width=\"36\" /\u003e\u0026nbsp;\u0026nbsp;\n  \u003cimg src=\"assets/icons/vscode.png\" alt=\"VS Code\" width=\"36\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/ai-agent-notifier\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/ai-agent-notifier?color=cb3837\u0026label=npm\" alt=\"npm version\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/ai-agent-notifier\"\u003e\u003cimg src=\"https://img.shields.io/npm/dm/ai-agent-notifier?color=blue\" alt=\"npm downloads\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/DevinoSolutions/ai-agent-notifier/blob/main/LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-AGPL--3.0-blue\" alt=\"License: AGPL-3.0\" /\u003e\u003c/a\u003e\n  \u003ca href=\"https://nodejs.org\"\u003e\u003cimg src=\"https://img.shields.io/badge/node-%3E%3D18-brightgreen\" alt=\"Node.js \u003e= 18\" /\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/dependencies-zero-success\" alt=\"Zero Dependencies\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Windows-0078D6?style=flat-square\u0026logo=windows\u0026logoColor=white\" alt=\"Windows\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/macOS-000000?style=flat-square\u0026logo=apple\u0026logoColor=white\" alt=\"macOS\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Linux-FCC624?style=flat-square\u0026logo=linux\u0026logoColor=black\" alt=\"Linux\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Android-3DDC84?style=flat-square\u0026logo=android\u0026logoColor=white\" alt=\"Android\" /\u003e\n  \u003cimg src=\"https://img.shields.io/badge/iOS-000000?style=flat-square\u0026logo=ios\u0026logoColor=white\" alt=\"iOS\" /\u003e\n\u003c/p\u003e\n\n---\n\n## Quick Start\n\n```bash\nnpx ai-agent-notifier setup\n```\n\nThat's it. The setup wizard detects your platform and installed AI tools, wires the hooks, and optionally configures phone push notifications. Restart your AI tools to activate.\n\n## Features\n\n- **Desktop toast notifications** -- Windows (BurntToast), macOS (Notification Center), Linux (libnotify)\n- **Phone push notifications** -- Android \u0026 iOS via [ntfy](https://ntfy.sh) (free, no account required)\n- **Click-to-focus** -- click the toast to jump back to the terminal or VS Code window (Windows)\n- **Per-tool branded icons** -- each tool gets its own logo in the notification\n- **One unified config** -- shared `~/.ai-agent-notifier/config.json` across all tools\n- **Atomic deduplication** -- prevents double notifications (e.g. Cursor's duplicate hook fires)\n- **Zero dependencies** -- pure Node.js built-ins only, no npm production packages\n\n## Supported Tools\n\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003cth\u003eTool\u003c/th\u003e\n    \u003cth\u003eVS Code\u003c/th\u003e\n    \u003cth\u003eCLI\u003c/th\u003e\n    \u003cth\u003eTask Complete\u003c/th\u003e\n    \u003cth\u003eNeeds Input\u003c/th\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"assets/icons/claude.png\" width=\"18\" /\u003e\u0026nbsp; \u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eNative\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eNative\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eStop\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eNotification\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"assets/icons/codex.png\" width=\"18\" /\u003e\u0026nbsp; \u003cstrong\u003eCodex CLI\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eNative\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eNative\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eStop\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003ePermissionRequest\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"assets/icons/cursor.png\" width=\"18\" /\u003e\u0026nbsp; \u003cstrong\u003eCursor\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eNative\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e--\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003estop\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e--\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003cimg src=\"assets/icons/gemini.png\" width=\"18\" /\u003e\u0026nbsp; \u003cstrong\u003eGemini CLI\u003c/strong\u003e\u003c/td\u003e\n    \u003ctd align=\"center\"\u003e--\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eNative\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eAfterAgent\u003c/code\u003e\u003c/td\u003e\n    \u003ctd\u003e\u003ccode\u003eNotification\u003c/code\u003e\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nAll four tools are wired automatically by the setup wizard. No manual config editing needed.\n\n### VS Code Native Support\n\nClaude Code, Codex, and Cursor all run inside VS Code. **ai-agent-notifier** hooks directly into each tool's native hook system -- no VS Code extension required. The setup wizard detects installed tools and patches their configs automatically. Click a notification toast to jump straight back to your VS Code window.\n\n## Installation\n\n### npm (recommended)\n\n```bash\n# One-shot setup (no install needed)\nnpx ai-agent-notifier setup\n\n# Or install globally\nnpm i -g ai-agent-notifier\nai-agent-notifier setup\n```\n\n### Claude Code Plugin\n\n```\n/install-plugin https://github.com/DevinoSolutions/ai-agent-notifier\n```\n\nHooks auto-register. Use `/ai-agent-notifier:setup` to wire other tools.\n\n### Standalone (no npm)\n\n**Windows (PowerShell):**\n```powershell\nirm https://raw.githubusercontent.com/DevinoSolutions/ai-agent-notifier/main/setup/install.ps1 | iex\n```\n\n**macOS / Linux:**\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DevinoSolutions/ai-agent-notifier/main/setup/install.sh | bash\n```\n\n## CLI Commands\n\n```\nai-agent-notifier setup          # First-time setup wizard\nai-agent-notifier status         # Show wired tools, config, backends\nai-agent-notifier test [channel] # Fire test notification (toast | ntfy | both)\nai-agent-notifier config         # Interactive settings menu\nai-agent-notifier uninstall      # Remove hooks from all tools\n```\n\n## Configuration\n\nConfig lives at `~/.ai-agent-notifier/config.json`:\n\n```json\n{\n  \"ntfy\": {\n    \"enabled\": true,\n    \"server\": \"https://ntfy.sh\",\n    \"topic\": \"ai-agent-notifier-\u003crandom\u003e\"\n  },\n  \"toast\": {\n    \"enabled\": true,\n    \"clickToFocus\": true\n  },\n  \"events\": {\n    \"task_complete\": { \"sound\": \"IM\", \"ntfyPriority\": \"default\" },\n    \"needs_input\": { \"sound\": \"Reminder\", \"ntfyPriority\": \"urgent\" },\n    \"session_start\": { \"sound\": \"Default\", \"ntfyPriority\": \"low\" }\n  }\n}\n```\n\n### ntfy -- Phone Push Notifications\n\n[ntfy](https://ntfy.sh) sends free push notifications to your phone -- no account needed.\n\n1. Install the ntfy app ([Android](https://play.google.com/store/apps/details?id=io.heckel.ntfy) / [iOS](https://apps.apple.com/app/ntfy/id1625396347))\n2. Subscribe to your topic (shown during setup)\n3. All your AI tools' notifications appear in one stream\n\n### Per-Event Settings\n\n| Event | Default Sound | ntfy Priority | Description |\n|-------|:------------:|:-------------:|-------------|\n| `task_complete` | IM | default | Agent finished its task |\n| `needs_input` | Reminder | urgent | Agent needs your input or permission |\n| `session_start` | Default | low | New session started (disabled by default) |\n\n## How It Works\n\nEach AI tool's hook system pipes event data to `notify.mjs`:\n\n```\nHook fires (stdin JSON + --source flag)\n  -\u003e parse-input.mjs   (normalize across tools)\n  -\u003e router.mjs        (map event to notification type)\n  -\u003e platform toast    (Windows / macOS / Linux)\n  -\u003e ntfy push         (phone notification)\n```\n\n## Platform Details\n\n### Windows\n\n- [BurntToast](https://github.com/Windos/BurntToast) PowerShell module for rich toast notifications\n- Click-to-focus via custom `agentfocus://` URI protocol\n- BurntToast auto-installed during setup if missing\n- Requires PowerShell 7+ (pwsh)\n\n### macOS\n\n- Uses built-in `osascript` -- zero additional dependencies\n- Falls back to `terminal-notifier` for richer features if available\n\n### Linux\n\n- Uses `notify-send` (libnotify) -- available on most desktop distributions\n- Fails silently on headless or WSL systems without a GUI\n\n## Requirements\n\n| Requirement | Details |\n|-------------|---------|\n| **Node.js** | \u003e= 18.0.0 (already present for all supported AI tools) |\n| **Windows** | PowerShell 7+ (pwsh) |\n| **macOS** | osascript (built-in) |\n| **Linux** | notify-send (optional, for desktop toasts) |\n\n## Uninstall\n\n```bash\nai-agent-notifier uninstall\n```\n\nRemoves all managed hooks from every tool's config. Original configs are backed up at `~/.ai-agent-notifier/backups/`.\n\n## Contributing\n\nContributions are welcome. Please open an issue first to discuss what you'd like to change.\n\n## License\n\n[AGPL-3.0](LICENSE) -- Copyright (c) 2026 [DevinoSolutions](https://github.com/DevinoSolutions)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevinosolutions%2Fai-agent-notifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevinosolutions%2Fai-agent-notifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevinosolutions%2Fai-agent-notifier/lists"}