cc-terminal-notifier

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:

npm install -g @matjic/[email protected]

Then add the following to your ~/.claude/settings.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/[email protected] 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:

{
  "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