You kick off Claude Code on a big task, and it runs autonomously for 5–15 minutes. You walk away to grab coffee, check your phone, or context-switch to something else. When you come back, Claude has been waiting for your input for the past 10 minutes. Time wasted.

This project sets up three independent notification channels so you never miss a prompt:

Claude Code needs your input
  │
  ├──→ terminal-notifier  →  macOS Notification Center  →  Mac banner + sound
  │
  ├──→ ntfy.sh (HTTP POST) →  ntfy server  →  ntfy app  →  iPhone / Apple Watch
  │
  └──→ Claude Code hook    →  plays custom alert sound via afplay

• Quick Start
• Manual Setup
  • 1. Install terminal-notifier
  • 2. Set Up ntfy.sh
  • 3. Configure CLAUDE.md
  • 4. Add Sound Hooks
  • 5. Grant Permissions
• Configuration Reference
• Security Notes
• Self-Hosting ntfy
• Troubleshooting
• Related Projects

• macOS (Apple Silicon or Intel)
• Homebrew
• Claude Code CLI installed
• iPhone with ntfy app or Android with ntfy app (optional but recommended)
• Apple Watch paired with iPhone (optional — notifications mirror automatically)

# 1. Clone the repo
git clone https://github.com/mingrath/claude-code-notify.git
cd claude-code-notify

# 2. Run the setup script
chmod +x setup.sh
./setup.sh

# 3. Follow the prompts to configure your ntfy topic name

The setup script will:

• Install terminal-notifier and ntfy via Homebrew
• Generate a unique topic name for you
• Set up notification sound files
• Output ready-to-paste config snippets

Or follow the manual setup below.

brew install terminal-notifier

Verify it works:

terminal-notifier -title "Test" -message "Hello from terminal!" -sound default

You should see a macOS notification banner.

ntfy.sh is a free, open-source push notification service. No account required.

Install the CLI (optional, for testing):

brew install ntfy

Choose a unique topic name:

Your topic name acts like a private channel. Pick something unique and hard to guess:

# Good — includes your name + random suffix
MY_TOPIC="yourname-claude-notify-x7k2"

# Bad — too generic, anyone could subscribe
MY_TOPIC="claude-notifications"

Test it:

# Terminal 1: Subscribe (or just open the topic in the ntfy app)
ntfy subscribe $MY_TOPIC

# Terminal 2: Send a test message
curl -d "Hello from Claude Code!" ntfy.sh/$MY_TOPIC

Install the ntfy app on your phone:

1. Install ntfy for iOS or ntfy for Android
2. Open the app and tap + to subscribe
3. Enter your topic name (e.g., yourname-claude-notify-x7k2)
4. Enable notifications when prompted
5. If you have an Apple Watch, notifications will automatically mirror from iPhone

Add this to your global ~/.claude/CLAUDE.md:

## Notifications

Whenever you need my decision or input, notify me via terminal-notifier before asking. If ntfy is available (Apple Watch), also send to ntfy.

```bash
terminal-notifier -title "Claude Code" -message "Your input is needed" -sound default && curl -s -d "Claude Code needs your input" ntfy.sh/YOUR_TOPIC_NAME > /dev/null 2>&1
```

Note: Replace YOUR_TOPIC_NAME with your chosen ntfy topic.

This tells Claude to run the notification command every time it needs your input.

Claude Code supports hooks — shell commands that fire on specific events. Add audio cues so you hear when Claude needs you or finishes a task.

Prepare sound files:

mkdir -p ~/.claude/sounds

# Use macOS built-in sounds, or add your own .mp3/.wav files
cp /System/Library/Sounds/Ping.aiff ~/.claude/sounds/need-human.aiff
cp /System/Library/Sounds/Glass.aiff ~/.claude/sounds/finish.aiff

Add hooks to ~/.claude/settings.json:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay -v 0.3 '$HOME/.claude/sounds/need-human.aiff'"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay -v 0.3 '$HOME/.claude/sounds/finish.aiff'"
          }
        ]
      }
    ]
  }
}

afplay is built into macOS. The -v flag controls volume (0.0 to 1.0).

Add terminal-notifier to your allowed commands in ~/.claude/settings.local.json:

{
  "permissions": {
    "allow": [
      "Bash(terminal-notifier:*)"
    ]
  }
}

This prevents Claude Code from prompting you to approve every notification command.

Here's the complete setup across all config files:

~/.claude/
├── CLAUDE.md                 # Notification instructions for Claude
├── settings.json             # Hooks (sound effects on events)
├── settings.local.json       # Permission grants
└── sounds/
    ├── need-human.aiff       # Played on Notification hook
    └── finish.aiff           # Played on Stop hook

Example files are provided in the examples/ directory — copy and adapt them.

$ claude "refactor the auth module and add tests"

  Claude is working autonomously...
  ⏳ 10 minutes pass — you're making coffee

  🔔 Mac:          notification banner pops up
  📱 iPhone:       push notification from ntfy
  ⌚ Apple Watch:  tap on your wrist
  🔊 Mac speakers: alert sound plays

  You walk back and see:
  "I've completed the refactor but need your input on
   the database migration strategy. Should I..."

For maximum privacy, run your own ntfy server:

# Using Docker
docker run -p 8080:80 binwiederhier/ntfy serve

# Update your CLAUDE.md to point to your server instead
# curl -d "message" http://localhost:8080/your-topic

See the ntfy self-hosting docs for full setup instructions.

# Check terminal-notifier is installed
which terminal-notifier

# Check macOS notification permissions
# System Settings → Notifications → terminal-notifier → Allow Notifications

# Test the topic directly
curl -d "test" ntfy.sh/your-topic-name

# Check the ntfy app:
# - Is the topic name correct?
# - Are notifications enabled for the ntfy app?
# - Is Do Not Disturb off?

# Test afplay manually
afplay -v 0.3 /System/Library/Sounds/Ping.aiff

# Check your sound file exists
ls -la ~/.claude/sounds/

• claude-code-statusline — Custom statusline for Claude Code showing real-time rate limit usage, context window %, session cost, and git status with progress bars. Pairs well with this notification setup for a complete "walk away" workflow.

• terminal-notifier by Julien Blanchard
• ntfy.sh by Philipp C. Heckel
• Claude Code by Anthropic

MIT