claude-code-notification

claude-code-notification

Never miss when Claude needs your attention.
A Claude Code plugin that sends push notifications when Claude finishes a task, encounters an error, or needs your input.

---

• Why?
• Installation
• Quick Start
• Watched Hook Events
• Configuration
  • Config files
  • Schema autocompletion
  • Configuration skill
  • Full config example
  • Merge behavior
• Backends
  • System Notification
  • ntfy
  • Sound
  • Custom Script
• Logs
• Security
• Contributing
• License

Why?

Long-running Claude tasks make it tempting to switch to another window or even another device. This plugin hooks into Claude Code's lifecycle events and notifies you through one or more backends — so you can context-switch freely and come back exactly when needed.

Supported backends include:

• ntfy: Push notifications to your phone or desktop via ntfy.sh or a self-hosted ntfy server

  Especially useful for remote claude code sessions

• Desktop notifications: Native OS notifications
• Sound: Play an audio file
• Custom scripts: Run your own scripts when claude needs attention

Installation

Inside Claude Code, run inside Claude Code:

/plugin marketplace add berk-karaal/claude-code-notification
/plugin install claude-code-notification@claude-code-notification

You need to restart Claude Code after first installation.

This project is currently developed for Linux and macOS. Windows support PRs are welcome!

Quick Start

After installation, open a new Claude Code session and use /claude-code-notification:configure skill to configure notifications you want to receive. By default, system notifications are enabled and everything else is disabled.

Example configuration skill usages:

/claude-code-notification:configure enable ntfy globally

/claude-code-notification:configure enable sound

/claude-code-notification:configure disable system notifications

/claude-code-notification:configure find me available sound files and let me choose one for each event

/claude-code-notification:configure disable all notifications for this project

Watched Hook Events

This plugin listens to these Claude Code hook events:

Event	When it fires	Notification title
Stop	Claude finishes a task	Claude Finished
Notification	Claude needs input (permission or idle prompt)	Claude Needs Input
StopFailure	Claude encounters an error	Claude Error

Configuration

Config files

Scope	Path
Global	~/.config/claude-code-notification/config.json
Per-project	.claude-code-notification.json in the project root

Per-project config merges with global at the field level — only set the fields you want to override.

Schema autocompletion

Add $schema to the top of your config file to get autocompletion and validation in your editor:

{
  "$schema": "https://raw.githubusercontent.com/berk-karaal/claude-code-notification/main/plugin/schema/config.schema.json"
}

Configuration skill

Inside Claude Code, use the built-in configuration skill:

Run skill without arguments to get an interactive configuration assistant:

/claude-code-notification:configure

You can also pass hints directly:

/claude-code-notification:configure enable ntfy per-project
/claude-code-notification:configure disable sound global

Claude will read the schema, ask clarifying questions if needed, and write a valid config file for you.

Full config example