cctoast

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 cctoast

Setup

cctoast install

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

To remove hooks:

cctoast uninstall

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

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx cctoast notify --event stop",
            "timeout": 10
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx cctoast notify --event notification",
            "timeout": 10
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx cctoast notify --event subagentStop",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUseFailure": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx cctoast 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 ~/.cctoast/config.json.

View current config

cctoast config --show

Change language

# Korean
cctoast config --language ko

# English (default)
cctoast config --language en

Toggle sound

cctoast config --sound off
cctoast config --sound on

Toggle events

cctoast config --event stop off
cctoast 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 installation:

cctoast 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