claude-code-toast

Native OS notifications for Claude Code events. Get notified when tasks complete, questions arise, subagents finish, or errors occur.

Supports macOS, Windows, Linux, and WSL.

Install

npm install -g claude-code-toast

Setup

claude-code-toast setup

This automatically adds hooks to ~/.claude/settings.json. Existing hooks are preserved.

To remove hooks:

claude-code-toast uninstall

Add the following hooks to your ~/.claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx claude-code-toast notify --event stop",
            "timeout": 10
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx claude-code-toast notify --event notification",
            "timeout": 10
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx claude-code-toast notify --event subagentStop",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx claude-code-toast notify --event postToolUseFailure",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

If you already have hooks in your settings.json, merge the entries above into the existing hooks object.

Events

| Event | When | |---|---| | stop | Claude finishes a task | | notification | Claude has a question or needs input | | subagentStop | A subagent completes | | postToolUseFailure | A tool (Bash, Edit, etc.) fails |

Configuration

Settings are stored at ~/.claude-code-toast/config.json.

View current config

claude-code-toast config --show

Change language

# Korean
claude-code-toast config --language ko

# English (default)
claude-code-toast config --language en

Toggle sound

claude-code-toast config --sound off
claude-code-toast config --sound on

Toggle events

claude-code-toast config --event stop off
claude-code-toast config --event notification on

Default config

{
  "version": 1,
  "events": {
    "stop": true,
    "notification": true,
    "subagentStop": false,
    "postToolUseFailure": false
  },
  "sound": true,
  "language": "en"
}

Test

Send a test notification to verify your setup:

claude-code-toast test

Platform Support

| Platform | Notification Method | |---|---| | macOS | Notification Center (via node-notifier) | | Windows | Toast Notification (via node-notifier) | | Linux | notify-send (via node-notifier) | | WSL | Windows Toast via powershell.exe (falls back to beep) |

License

MIT