claude-code-notify
claude-code-notify sends a desktop notification whenever Claude Code finishes responding, so you never miss a prompt while working across mu
Open source Open in the app JSON README (API)
About
claude-code-notify sends a desktop notification whenever Claude Code finishes responding, so you never miss a prompt while working across multiple sessions. Each notification shows your session name (from /rename) and the first 80 characters of Claude's last response, giving you context at a glance. When running in tmux, the notification includes the window index so you know exactly where to switch. The plugin is focus-aware: if you're already looking at the Claude session (detected via tmux pane, window, and terminal focus state), the notification is suppressed. On macOS without tmux, it checks whether your terminal app is frontmost. A 5-second debounce prevents notification spam during rapid tool calls. Works on Linux (notify-send) and macOS (osascript). Requires jq and bash 4+. tmux is optional but recommended for the best experience. Configuration is zero-config by default, with two optional environment variables: CLAUDE_NOTIFY_CONTEXT (adds a Work/Personal prefix) and CLAUDE_NOTIF
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- decko
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 1
- Last push
- 2026-03-26T23:17:39Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
decko/claude-code-notify/claude-code-notify
README
# claude-code-notify
Smart desktop notifications for [Claude Code](https://claude.com/claude-code). Get notified when Claude finishes responding — with session name, last message, and tmux context. Focus-aware: won't bother you if you're already looking.
## What It Does
When Claude Code stops and is waiting for your input, you get a notification like:
```
(w:2) my-project
Fixed the authentication bug by updating the session config...
```
- **Session name** from `/rename` (falls back to directory name)
- **Last message** — first 80 chars of what Claude said
- **tmux window index** — so you know where to switch
- **Focus-aware** — no notification if you're already looking at the session
## Install
### As a Claude Code Plugin
```bash
# Clone the repo
git clone https://github.com/decko/claude-code-notify.git ~/.claude/plugins/claude-code-notify
# Enable in Claude Code
claude plugins add claude-code-notify
```
### Manual
Copy `hooks/stop-hook.sh` and register in your `~/.claude/settings.json`:
```json
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "bash /path/to/stop-hook.sh"
}
]
}
]
}
}
```
## Requirements
- `jq` — JSON parsing
- `notify-send` (Linux) or `osascript` (macOS) — notifications
- `tmux` (optional) — focus detection and window index
- `bash` 4+
### Installing Dependencies
**Fedora/RHEL:**
```bash
sudo dnf install jq libnotify
```
**Ubuntu/Debian:**
```bash
sudo apt install jq libnotify-bin
```
**macOS:**
```bash
brew install jq
# osascript is built-in
```
## Configuration
Set environment variables in your shell profile (`.bashrc`, `.zshrc`):
| Variable | Default | Description |
|---|---|---|
| `CLAUDE_NOTIFY_CONTEXT` | `false` | Show `[Work]`/`[Personal]` prefix |
| `CLAUDE_NOTIFY_URGENCY` | `normal` | Urgency: `low`, `normal`, `critical` |
Example:
```bash
export CLAUDE_NOTIFY_CONTEXT=true
export CLAUDE_NOTIFY_URGENCY=normal
```
## Commands
| Command | Description |
|---|---|
| `/notify-help` | Show configuration and status |
| `/notify-test` | Send a test notification |
## Use Cases
- **Multi-session development in tmux** — Running Claude in 3-4 tmux panes working on different tasks (tests, refactoring, docs). Get notified exactly when each session needs your attention, without constantly switching panes to check.
- **Long-running operations** — Kick off a complex task (large codebase refactor, test suite run, dependency upgrade) and switch to other work. The notification tells you when Claude is done and what it said.
- **Code review while Claude works** — Send Claude a task, switch to your browser to review a PR or read docs. The notification pops up when Claude needs your input, with enough context in the body to decide if it's urgent.
- **Pair programming across projects** — Working on a primary project while Claude handles a side task in another session. The window index in the notification (`w:2`) tells you exactly which tmux window to jump to.
- **Meeting multitasking** — Start a Claude task before a meeting, get a notification when it's done. Check it when the meeting ends.
## Focus Detection
The plugin suppresses notifications when you're already looking at the Claude session:
| Environment | Method | Notes |
|---|---|---|
| tmux | Pane + window + terminal focus | Best experience |
| macOS (no tmux) | Frontmost app check | Detects Terminal, iTerm2, kitty, etc. |
| Linux (no tmux) | Always notify | Wayland limits focus detection |
## How It Works
1. Claude Code fires the Stop hook when it finishes responding
2. The hook reads the payload (session ID, last message, transcript path)
3. Checks if the tmux pane is focused — skips notification if so
4. Resolves the session name from `/rename` history in the transcript
5. Sends a notification with session name and last message
## Interaction with Other Plugins
If another Stop hook (like ralph-loop) continues the conversation, the `stop_hook_active` flag is set and this plugin skips the notification. Due to non-deterministic hook ordering, occasional false-positive notifications may occur when ralph-loop is active.
## License
MIT