mac-notifier
Skill2 starsChanged 10 months agoMITView on GitHub
Send native macOS notifications when Claude Code completes tasks or awaits user input. Use when user wants to set up desktop notifications, enable alerts for task completion, or configure Claude Code hooks for background monitoring.
- Installs packages
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- mermaid-to-imgSkill
- text-to-audioSkill
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 7 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 24
Use the installation script to configure hooks in your Claude Code settings:
- Distinctive: line 42
Add notification hooks for task completion and user input prompts
- Distinctive: line 43
Test the notification to verify it works
- Very specific: line 78
If you prefer manual configuration, add the following to your ~/.claude/settings.json:
- Distinctive: line 237
Check System Settings → Notifications → Script Editor is enabled
- Distinctive: line 238
Ensure Terminal/iTerm has notification permissions
- Very specific: line 239
Verify the script has execute permissions: chmod +x notify.sh
- Distinctive: line 243
Check system volume is not muted
- Distinctive: line 244
Verify the sound name is spelled correctly (case-sensitive)
- Very specific: line 249
Ensure jq is installed: brew install jq
- Very specific: line 250
Check if ~/.claude/settings.json is valid JSON
- Very specific: line 251
Run ./scripts/install.sh status to see current configuration
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Mac Notifier for Claude Code
A lightweight utility that sends native macOS notifications when Claude Code events occur, such as task completion or waiting for user input.
Features
- Native macOS notifications via AppleScript
- Customizable notification sounds
- Support for task completion, permission request, and MCP elicitation events
- i18n support: Auto-detect language from
$LANG(zh/en) - Directory info: Show project directory in notification subtitle
- Zero external dependencies (except
jqfor installation script)
Installation
Use the installation script to configure hooks in your Claude Code settings:
# Install hooks to Claude Code
./scripts/install.sh install
# With custom sounds
./scripts/install.sh install --stop-sound Hero --permission-sound Pop
# With Chinese locale and directory info
./scripts/install.sh install --locale zh --directory-format short
# With English locale and full directory path
./scripts/install.sh install --locale en --directory-format fullThis will automatically:
- Backup your existing
~/.claude/settings.json - Add notification hooks for task completion and user input prompts
- Test the notification to verify it works
Uninstall
./scripts/install.sh uninstallCheck Status
./scripts/install.sh statusInstallation Script Options
./scripts/install.sh [COMMAND] [OPTIONS]
Commands:
install Install hooks to Claude Code settings (default)
uninstall Remove hooks from Claude Code settings
status Show current hooks configuration
test Test notification functionality
help Show help message
Options for install:
--stop-sound SOUND Sound for task completion (default: Glass)
--permission-sound SOUND Sound for permission prompt (default: Funk)
--locale LOCALE Language: zh|en (default: auto-detect from $LANG)
--directory-format FMT Directory format: short|full|none (default: none)Manual Configuration
If you prefer manual configuration, add the following to your ~/.claude/settings.json:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/mac-notifier/scripts/notify.sh -k task_completed --locale zh --directory-format short"
}
]
}
],
"PermissionRequest": [
{
"hooks": [
{
"type": "command",
"command": "/path/to/mac-notifier/scripts/notify.sh -k permission_needed --locale zh --directory-format short -s Funk"
}
]
}
],
"Notification": [
{
"matcher": "elicitation_dialog",
"hooks": [
{
"type": "command",
"command": "/path/to/mac-notifier/scripts/notify.sh -k input_needed --locale zh --directory-format short -s Ping"
}
]
}
]
}
}Notification Script Usage
# Basic notification
./scripts/notify.sh -m "Hello World"
# With custom title
./scripts/notify.sh -t "My App" -m "Process finished"
# With subtitle
./scripts/notify.sh -m "Build successful" --subtitle "Project: my-app"
# With custom sound
./scripts/notify.sh -m "Attention needed" -s Ping
# Silent notification (no sound)
./scripts/notify.sh -m "Silent update" --no-sound
# Using predefined message key with localization
./scripts/notify.sh -k task_completed --locale zh
# With directory info (project name)
./scripts/notify.sh -k task_completed --directory-format short
# With full directory path
./scripts/notify.sh -m "Build done" --directory-format full
# Show help
./scripts/notify.sh --helpParameters
| Parameter | Description |
-t, --title | Notification title (default: Claude Code) |
-m, --message | Notification message |
-k, --message-key | Predefined message key: task_completed, permission_needed, input_needed |
-s, --sound | Sound name (default: Glass) |
--subtitle | Notification subtitle |
--locale | Language: zh or en (default: auto-detect from $LANG) |
--directory-format | Directory format: short (project name), full (absolute path), none |
--no-sound | Disable notification sound |
-h, --help | Show help message |
Localization
The script supports Chinese (zh) and English (en) localization:
| Message Key | English | Chinese |
task_completed | Task completed | 任务已完成 |
permission_needed | Permission needed | 需要权限确认 |
input_needed | Input needed for MCP tool | MCP 工具需要输入 |
Language is auto-detected from $LANG environment variable, or can be specified via --locale parameter.
Directory Format
The --directory-format option controls how directory info is displayed in the notification subtitle:
| Format | Description | Example |
short | Project name (basename) | skills |
full | Full absolute path | /Users/tian/osproject/zth9/skills |
none | No directory info (default) | - |
Directory detection priority:
CLAUDE_PROJECT_DIRenvironment variable (set by Claude Code)- Git repository root directory
- Current working directory (
PWD)
Available Sounds
macOS provides the following built-in notification sounds:
| Sound | Description |
Basso | Low-pitched alert |
Blow | Soft whoosh |
Bottle | Cork pop |
Frog | Frog croak |
Funk | Funky tone |
Glass | Glass tap (default) |
Hero | Heroic fanfare |
Morse | Morse code beep |
Ping | Clear ping |
Pop | Pop sound |
Purr | Cat purr |
Sosumi | Classic Mac alert |
Submarine | Submarine sonar |
Tink | Light tap |
Hook Events
Claude Code supports several hook events that can trigger notifications:
| Event | Description |
Stop | Claude completes its response (immediate notification) |
PermissionRequest | When permission dialog appears (immediate notification) |
Notification with elicitation_dialog | When Claude Code needs input for MCP tool elicitation |
SubagentStop | A sub-agent task completes |
PostToolUse | After a tool executes successfully |
Note: This skill uses
Stop,PermissionRequest, andNotification(elicitation_dialog) hooks which trigger immediately when human intervention is needed. Theidle_promptis not used because it has a built-in 60-second delay.
How It Works
The installation script modifies your ~/.claude/settings.json to register hooks:
- Stop Hook: Triggered immediately when Claude finishes responding to your request
- PermissionRequest Hook: Triggered immediately when Claude needs permission to execute a command
- Notification Hook (elicitation_dialog): Triggered when Claude needs input for MCP tool
Troubleshooting
Notifications Not Appearing
- Check System Settings → Notifications → Script Editor is enabled
- Ensure Terminal/iTerm has notification permissions
- Verify the script has execute permissions:
chmod +x notify.sh
No Sound Playing
- Check system volume is not muted
- Verify the sound name is spelled correctly (case-sensitive)
- Try a different sound name
Installation Issues
- Ensure
jqis installed:brew install jq - Check if
~/.claude/settings.jsonis valid JSON - Run
./scripts/install.sh statusto see current configuration
License
MIT
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

