https://github.com/kratocz/desktop-notify
Claude Code plugin — desktop notifications when Claude waits for your response or approval
https://github.com/kratocz/desktop-notify
claude-code claude-plugin desktop-notifications hooks linux macos
Last synced: about 2 months ago
JSON representation
Claude Code plugin — desktop notifications when Claude waits for your response or approval
- Host: GitHub
- URL: https://github.com/kratocz/desktop-notify
- Owner: kratocz
- Created: 2026-03-23T18:52:41.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T14:42:16.000Z (3 months ago)
- Last Synced: 2026-03-24T17:13:22.245Z (3 months ago)
- Topics: claude-code, claude-plugin, desktop-notifications, hooks, linux, macos
- Language: Shell
- Size: 28.3 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# desktop-notify
A [Claude Code](https://claude.ai/claude-code) plugin that sends desktop notifications whenever Claude is waiting for your response or needs your approval to run a tool.
Never miss a paused session again — get notified even when you're in another window.
## Preview
## What it does
| Event | When | Notification example |
|---|---|---|
| `Stop` | Claude finished its response | `Claude Code – myproject` / `Waiting for your response` |
| `PermissionRequest` | Claude needs tool approval | `Claude Code – myproject` / `Approval: Bash: git status` |
Each notification includes the **project name** in the title so you always know which Claude Code session needs attention.
## Configuration
Set `DESKTOP_NOTIFY_METHOD` in your `~/.claude/settings.json` to choose how you're notified:
```json
{
"env": {
"DESKTOP_NOTIFY_METHOD": "visual"
}
}
```
| Value | Behavior |
|---|---|
| `visual` | Desktop notification popup *(default)* |
| `sound` | Text-to-speech reads the project name and message aloud |
| `both` | Visual notification + TTS simultaneously |
## Requirements
| Platform | `visual` | `sound` |
|---|---|---|
| Linux | `notify-send` (libnotify) + `jq` | `spd-say`, `espeak-ng`, or `espeak` |
| macOS | `jq` (notifications via built-in `osascript`) | built-in `say` |
| Windows | Not supported yet | Not supported yet |
### Install dependencies
**Ubuntu / Debian:**
```bash
sudo apt install libnotify-bin jq
# for sound:
sudo apt install speech-dispatcher # provides spd-say
```
**Fedora / RHEL:**
```bash
sudo dnf install libnotify jq
# for sound:
sudo dnf install speech-dispatcher
```
**macOS:**
```bash
brew install jq
# sound uses built-in 'say' — no extra dependencies
```
## Installation
```
/plugin marketplace add kratocz/claude-plugins
/plugin install desktop-notify@kratocz
```
## How it works
The plugin registers two [Claude Code hook](https://docs.anthropic.com/en/docs/claude-code/hooks) events:
- **`Stop`** — fires when Claude finishes its response and waits for your next message
- **`PermissionRequest`** — fires when Claude needs your approval to execute a tool (Bash command, file write, etc.)
Both hooks run **asynchronously** so they never slow down Claude Code.
The `PermissionRequest` notification includes the tool name and a short preview of the command or file path, so you immediately know what needs your attention.
## Acknowledgements
Sound notification support was inspired by [Radim Klaška](https://github.com/radimklaska).
## Contributing
Issues and PRs are welcome at [github.com/kratocz/desktop-notify](https://github.com/kratocz/desktop-notify).
## License
MIT — © [Petr Kratochvíl](https://krato.cz/)