{"id":43596615,"url":"https://github.com/mylee04/code-notify","last_synced_at":"2026-04-06T21:01:22.525Z","repository":{"id":307131568,"uuid":"1028437757","full_name":"mylee04/code-notify","owner":"mylee04","description":"Cross-platform desktop notifications for Claude Code, Codex, and Gemini CLI. Install via Homebrew, npm, or script.","archived":false,"fork":false,"pushed_at":"2026-04-02T21:51:30.000Z","size":1291,"stargazers_count":170,"open_issues_count":4,"forks_count":17,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T00:38:11.260Z","etag":null,"topics":["anthropic-claude","claude","claude-code","codex","codex-cli","desktop-notifications","developer-tools","gemini","gemini-ai","gemini-cli","google-gemini","homebrew","linux","macos","notifications","npm","openai-codex","openai-codex-cli","productivity","windows"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/mylee04.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","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":"2025-07-29T14:26:05.000Z","updated_at":"2026-04-02T21:51:23.000Z","dependencies_parsed_at":"2025-07-29T17:34:49.547Z","dependency_job_id":"640163b5-c1e2-43b7-b84f-b692d2849cc4","html_url":"https://github.com/mylee04/code-notify","commit_stats":null,"previous_names":["mylee04/claude-notify","mylee04/code-notify"],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/mylee04/code-notify","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mylee04%2Fcode-notify","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mylee04%2Fcode-notify/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mylee04%2Fcode-notify/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mylee04%2Fcode-notify/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mylee04","download_url":"https://codeload.github.com/mylee04/code-notify/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mylee04%2Fcode-notify/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31489427,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"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":["anthropic-claude","claude","claude-code","codex","codex-cli","desktop-notifications","developer-tools","gemini","gemini-ai","gemini-cli","google-gemini","homebrew","linux","macos","notifications","npm","openai-codex","openai-codex-cli","productivity","windows"],"created_at":"2026-02-04T04:06:40.975Z","updated_at":"2026-04-06T21:01:22.519Z","avatar_url":"https://github.com/mylee04.png","language":"Shell","readme":"# Code-Notify\n\n\u003e **Official downloads**: https://github.com/mylee04/code-notify/releases\n\u003e\n\u003e **Homebrew**: `brew install mylee04/tools/code-notify`\n\u003e\n\u003e **npm**: `npm install -g code-notify`\n\nDesktop notifications for AI coding tools - get alerts when tasks complete or input is needed.\n\n\u003cp\u003e\n  \u003cimg src=\"assets/multi-tools-support.png\" width=\"48%\" alt=\"Multi-tool support\"/\u003e\n  \u003cimg src=\"assets/multi-tools-support-02.png\" width=\"48%\" alt=\"All tools enabled\"/\u003e\n\u003c/p\u003e\n\n[![Version](https://img.shields.io/badge/version-1.7.2-blue.svg)](https://github.com/mylee04/code-notify/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![macOS](https://img.shields.io/badge/macOS-supported-green.svg)](https://www.apple.com/macos)\n[![Linux](https://img.shields.io/badge/Linux-supported-green.svg)](https://www.linux.org/)\n[![Windows](https://img.shields.io/badge/Windows-supported-green.svg)](https://www.microsoft.com/windows)\n\n---\n\n## What's New in v1.7.2\n\n- **`curl` installs now fetch the full click-through runtime**: non-Homebrew installs on macOS and Linux now download the click-through helper files that `cn status`, notifier activation, and click-through commands expect\n- **Fixes a real install regression after the click-through refactor**: raw installs no longer fail with missing `click-through*.sh` files after installation\n- **Homebrew, npm, and script installs stay aligned again**: all supported install paths now ship the same click-through runtime layout\n\n---\n\n## Features\n\n- **Multi-tool support** - Claude Code, OpenAI Codex, Google Gemini CLI\n- **Works everywhere** - Terminal, VSCode, Cursor, or any editor\n- **Cross-platform** - macOS, Linux, Windows\n- **Native notifications** - Uses system notification APIs\n- **macOS click-through control** - Choose which app notification clicks activate\n- **Sound notifications** - Play custom sounds on task completion\n- **Voice announcements** - Hear when tasks complete (macOS, Windows)\n- **Tool-specific messages** - \"Claude completed the task\", \"Codex completed the task\"\n- **Project-specific settings** - Different configs per project\n- **Quick aliases** - `cn` and `cnp` for fast access\n\n## Installation\n\n### For Humans\n\n**macOS (Homebrew)**\n\n```bash\nbrew tap mylee04/tools\nbrew install code-notify\ncn on\n```\n\n**macOS (Homebrew, Already Installed)**\n\n```bash\ncn update\ncode-notify version\n```\n\nIf you were using the older `claude-notify` hook layout, supported upgrades now repair those Claude hooks automatically. On Windows, that repair also covers older `notify.ps1` hook layouts and alternate Claude settings locations such as `%USERPROFILE%\\.config\\.claude\\settings.json`.\n\n**Linux / WSL**\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/mylee04/code-notify/main/scripts/install.sh | bash\n```\n\n**npm (macOS / Linux / Windows)**\n\n```bash\nnpm install -g code-notify\ncn on\n```\n\n**Windows**\n\n```powershell\nirm https://raw.githubusercontent.com/mylee04/code-notify/main/scripts/install-windows.ps1 | iex\n```\n\n### For LLM Agents\n\nPaste this to your AI agent (Claude Code, Cursor, etc.):\n\n```\nInstall code-notify by following:\nhttps://raw.githubusercontent.com/mylee04/code-notify/main/docs/installation.md\n```\n\nOr fetch directly:\n\n```bash\ncurl -s https://raw.githubusercontent.com/mylee04/code-notify/main/docs/installation.md\n```\n\n## Usage\n\n![cn help output](assets/cn-help.png)\n\n| Command              | Description                                  |\n| -------------------- | -------------------------------------------- |\n| `cn on`              | Enable notifications for all detected tools  |\n| `cn on all`          | Explicit alias for enabling all detected tools |\n| `cn on claude`       | Enable for Claude Code only                  |\n| `cn on codex`        | Enable for Codex only                        |\n| `cn on gemini`       | Enable for Gemini CLI only                   |\n| `cn off`             | Disable notifications                        |\n| `cn off all`         | Explicit alias for disabling all tools       |\n| `cn test`            | Send test notification                       |\n| `cn status`          | Show current status                          |\n| `cn update`          | Update code-notify                           |\n| `cn update check`    | Check the latest release and show the update command |\n| `cn click-through`   | Show current macOS click-through mappings    |\n| `cn click-through add \u003capp\u003e` | Add a macOS click-through mapping    |\n| `cn alerts`          | Configure which events trigger notifications |\n| `cn sound on`        | Enable sound notifications                   |\n| `cn sound set \u003cpath\u003e`| Use custom sound file                        |\n| `cn voice on`        | Enable voice (macOS, Windows)                |\n| `cn voice on claude` | Enable voice for Claude only                 |\n| `cnp on`             | Enable for current project only              |\n\nWhen enabling project notifications with `cnp on`, Code-Notify warns if Claude project trust does not appear to be accepted yet.\nProject-scoped Claude hooks override the global mute file, so `cn off` will not suppress a project where `cnp on` is enabled.\n`all` is also accepted as an explicit alias for global commands such as `cn on all`, `cn off all`, and `cn status all`.\n\n## How It Works\n\nCode-Notify uses the hook systems built into AI coding tools:\n\n- **Claude Code**: `~/.claude/settings.json`\n- **Codex**: `~/.codex/config.toml`\n- **Gemini CLI**: `~/.gemini/settings.json`\n\nFor Codex, Code-Notify configures `notify = [\"/absolute/path/to/notifier.sh\", \"codex\"]` and reads the JSON payload Codex appends on completion.\nCodex currently exposes completion events through `notify`; approval and `request_permissions` prompts do not currently arrive through this hook.\n\nWhen enabled, it adds hooks that call the notification script when tasks complete:\n\n```json\n{\n  \"hooks\": {\n    \"Stop\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"notify.sh stop claude\" }]\n      }\n    ],\n    \"Notification\": [\n      {\n        \"matcher\": \"idle_prompt\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"notify.sh notification claude\" }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Alert Types\n\n\u003cimg src=\"assets/cn-status-v1.4.0.png\" width=\"60%\" alt=\"cn status showing alert types\"/\u003e\n\nBy default, notifications only fire when the AI is idle and waiting for input (`idle_prompt`). You can customize this:\n\n```bash\ncn alerts                          # Show current config\ncn alerts add permission_prompt    # Also notify on tool permission requests\ncn alerts remove permission_prompt # Remove permission notifications\ncn alerts reset                    # Back to default (idle_prompt only)\n```\n\n| Type                 | Description                            |\n| -------------------- | -------------------------------------- |\n| `idle_prompt`        | AI is waiting for your input (default) |\n| `permission_prompt`  | AI needs tool permission (Y/n)         |\n| `auth_success`       | Authentication success                 |\n| `elicitation_dialog` | MCP tool input needed                  |\n\nAlert-type matching currently applies to Claude Code and Gemini CLI notification hooks. Codex currently uses completion events from `notify`, so `permission_prompt` and `idle_prompt` settings do not change Codex behavior.\n\n## Troubleshooting\n\n**Command not found?**\n\n```bash\nexec $SHELL   # Reload shell\n```\n\n**No notifications?**\n\n```bash\ncn status     # Check if enabled\ncn test       # Test notification\nbrew install terminal-notifier  # Better notifications (macOS)\n```\n\n**Notification click opens the wrong macOS app?**\n\n```bash\ncn click-through add PhpStorm\ncn test\n```\n\n**Installed with npm?**\n\n```bash\ncn update     # Runs: npm install -g code-notify@latest\n```\n\n**Too many `last_notification_*` files in `~/.claude/notifications`?**\n\nGenerated rate-limit state files are stored under `~/.claude/notifications/state/` instead of cluttering the root notifications folder.\n\n## Project Structure\n\n```\ncode-notify/\n├── bin/           # Main executable\n├── lib/           # Library code\n├── scripts/       # Install scripts\n├── docs/          # Documentation\n└── assets/        # Images\n```\n\n## Links\n\n- [Installation Guide](docs/installation.md)\n- [Hook Configuration](docs/HOOKS_GUIDE.md)\n- [Contributing](docs/CONTRIBUTING.md)\n- [GitHub Issues](https://github.com/mylee04/code-notify/issues)\n\n## License\n\nMIT License - see [LICENSE](LICENSE)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmylee04%2Fcode-notify","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmylee04%2Fcode-notify","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmylee04%2Fcode-notify/lists"}