agentleFS
zth9zth9/skills/mac-notifier/SKILL.md

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

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
  1. Distinctive:

    Use the installation script to configure hooks in your Claude Code settings:

    line 24
  2. Distinctive:

    Add notification hooks for task completion and user input prompts

    line 42
  3. Distinctive:

    Test the notification to verify it works

    line 43
  4. Very specific:

    If you prefer manual configuration, add the following to your ~/.claude/settings.json:

    line 78
  5. Distinctive:

    Check System Settings → Notifications → Script Editor is enabled

    line 237
  6. Distinctive:

    Ensure Terminal/iTerm has notification permissions

    line 238
  7. Very specific:

    Verify the script has execute permissions: chmod +x notify.sh

    line 239
  8. Distinctive:

    Check system volume is not muted

    line 243
  9. Distinctive:

    Verify the sound name is spelled correctly (case-sensitive)

    line 244
  10. Very specific:

    Ensure jq is installed: brew install jq

    line 249
  11. Very specific:

    Check if ~/.claude/settings.json is valid JSON

    line 250
  12. Very specific:

    Run ./scripts/install.sh status to see current configuration

    line 251

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 jq for 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 full

This will automatically:

  1. Backup your existing ~/.claude/settings.json
  2. Add notification hooks for task completion and user input prompts
  3. Test the notification to verify it works

Uninstall

./scripts/install.sh uninstall

Check Status

./scripts/install.sh status

Installation 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 --help

Parameters

ParameterDescription
-t, --titleNotification title (default: Claude Code)
-m, --messageNotification message
-k, --message-keyPredefined message key: task_completed, permission_needed, input_needed
-s, --soundSound name (default: Glass)
--subtitleNotification subtitle
--localeLanguage: zh or en (default: auto-detect from $LANG)
--directory-formatDirectory format: short (project name), full (absolute path), none
--no-soundDisable notification sound
-h, --helpShow help message

Localization

The script supports Chinese (zh) and English (en) localization:

Message KeyEnglishChinese
task_completedTask completed任务已完成
permission_neededPermission needed需要权限确认
input_neededInput needed for MCP toolMCP 工具需要输入

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:

FormatDescriptionExample
shortProject name (basename)skills
fullFull absolute path/Users/tian/osproject/zth9/skills
noneNo directory info (default)-

Directory detection priority:

  1. CLAUDE_PROJECT_DIR environment variable (set by Claude Code)
  2. Git repository root directory
  3. Current working directory (PWD)

Available Sounds

macOS provides the following built-in notification sounds:

SoundDescription
BassoLow-pitched alert
BlowSoft whoosh
BottleCork pop
FrogFrog croak
FunkFunky tone
GlassGlass tap (default)
HeroHeroic fanfare
MorseMorse code beep
PingClear ping
PopPop sound
PurrCat purr
SosumiClassic Mac alert
SubmarineSubmarine sonar
TinkLight tap

Hook Events

Claude Code supports several hook events that can trigger notifications:

EventDescription
StopClaude completes its response (immediate notification)
PermissionRequestWhen permission dialog appears (immediate notification)
Notification with elicitation_dialogWhen Claude Code needs input for MCP tool elicitation
SubagentStopA sub-agent task completes
PostToolUseAfter a tool executes successfully

Note: This skill uses Stop, PermissionRequest, and Notification (elicitation_dialog) hooks which trigger immediately when human intervention is needed. The idle_prompt is 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:

  1. Stop Hook: Triggered immediately when Claude finishes responding to your request
  2. PermissionRequest Hook: Triggered immediately when Claude needs permission to execute a command
  3. Notification Hook (elicitation_dialog): Triggered when Claude needs input for MCP tool

Troubleshooting

Notifications Not Appearing

  1. Check System Settings → Notifications → Script Editor is enabled
  2. Ensure Terminal/iTerm has notification permissions
  3. Verify the script has execute permissions: chmod +x notify.sh

No Sound Playing

  1. Check system volume is not muted
  2. Verify the sound name is spelled correctly (case-sensitive)
  3. Try a different sound name

Installation Issues

  1. Ensure jq is installed: brew install jq
  2. Check if ~/.claude/settings.json is valid JSON
  3. Run ./scripts/install.sh status to see current configuration

License

MIT

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.