terminal-notifier
Sends notifications that take you to the right claude code session when clicked
Open source Open in the app JSON README (API)
About
Sends notifications that take you to the right claude code session when clicked
Details
- Kind
- Plugins
- Topic
- Developer tools
- Publisher
- matjic
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 1
- Last push
- 2026-02-28T23:34:53Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
matjic/cc-terminal-notifier/terminal-notifier
README
# cc-terminal-notifier
Claude Code hook that sends native terminal notifications (bell, OSC escape sequences) when Claude Code needs your attention.
## Install (Plugin)
```
/plugin marketplace add matjic/cc-terminal-notifier
/plugin install cc-terminal-notifier
```
That's it — hooks are registered automatically.
## Install (Manual)
If you prefer manual setup, install globally via npm:
```bash
npm install -g @matjic/cc-terminal-notifier@0.1.0
```
Then add the following to your `~/.claude/settings.json`:
```json
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|idle_prompt|elicitation_dialog",
"hooks": [
{
"type": "command",
"command": "cc-terminal-notifier"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "cc-terminal-notifier"
}
]
}
],
"SubagentStop": [
{
"hooks": [
{
"type": "command",
"command": "cc-terminal-notifier"
}
]
}
]
}
}
```
Or run directly with npx (replace `cc-terminal-notifier` with `npx @matjic/cc-terminal-notifier@0.1.0` in the hooks above).
## Supported Terminals
| Terminal | Method | Notification Style |
| --- | --- | --- |
| Kitty | OSC 99 | Desktop notification with title + body |
| WezTerm | OSC 99 | Desktop notification with title + body |
| foot | OSC 99 | Desktop notification with title + body |
| Ghostty | OSC 777 | Desktop notification with title + body |
| iTerm2 | OSC 9 | Desktop notification with message |
| All others | Bell | Terminal bell (flash/sound) |
## Configuration
Optionally create `~/.config/claude-code/terminal-notifier.json` to customize behavior:
```json
{
"enabled": true,
"method": "auto",
"showProjectName": true,
"events": {
"permission": { "enabled": true },
"complete": { "enabled": true },
"subagent_complete": { "enabled": false },
"question": { "enabled": true }
},
"messages": {
"permission": "Claude Code needs permission",
"complete": "Claude Code has finished",
"subagent_complete": "Subagent task completed",
"question": "Claude Code has a question"
}
}
```
### Options
- **enabled** — Global on/off switch (default: `true`)
- **method** — Notification method: `"auto"`, `"bell"`, `"osc9"`, `"osc777"`, `"osc99"` (default: `"auto"` — auto-detects from `TERM_PROGRAM`)
- **showProjectName** — Include project directory name in notification title (default: `true`)
- **events** — Per-event overrides. Each event can have:
- **enabled** — Enable/disable this event (or use `true`/`false` shorthand)
- **method** — Override the notification method for this event
- **messages** — Custom notification messages per event type
### Event Types
| Event | Hook | Default |
| --- | --- | --- |
| `permission` | Notification (permission_prompt) | Enabled |
| `question` | Notification (idle_prompt, elicitation_dialog) | Enabled |
| `complete` | Stop | Disabled |
| `subagent_complete` | SubagentStop | Disabled |
## Troubleshooting
**No notification appears:**
- Check that your terminal supports the detected method, or set `method` explicitly in the config
- Verify the hook is configured correctly in `~/.claude/settings.json`
- Test manually: `echo '{"hook_event_name":"Notification","notification_type":"permission_prompt","cwd":"/tmp","session_id":"test","transcript_path":"","permission_mode":"default","message":"test"}' | cc-terminal-notifier`
**Notification goes to wrong output:**
- The tool writes escape sequences to `/dev/tty` directly, avoiding stdout. If `/dev/tty` is unavailable, it falls back to stderr.
## License
Apache-2.0