cc-terminal-notifier
Native terminal notifications when Claude Code needs your attention
Open source Open in the app JSON README (API)
About
Native terminal notifications when Claude Code needs your attention
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/cc-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