Windows Toast Notifications - Main README with cross-platform overview and Claude Code hooks documentation

README.md

Windows Toast Notifications for WSL

This package provides cross-platform toast notification functionality for Windows and WSL (Windows Subsystem for Linux). Perfect for Claude Code hooks and other automation tasks.

Features

• 🔔 Native Windows toast notifications using BurntToast PowerShell module
• 🐧 WSL integration with simple toast command
• 🔧 Easy installation with automatic dependency handling
• ✨ Works great with Claude Code hooks
• 🎯 Supports both title and body text

Installation Guides

Choose your installation method:

🪟 Windows Installation

For Windows PowerShell/CMD environments

👉 Windows Installation Guide

Quick install:

Invoke-WebRequest 'https://gist.githubusercontent.com/ChrisColeTech/46928a028d372a0453d743de02c0a2f8/raw/6c15441bd22ad0635181e5cb27c92010bac06af7/windows_toast_install.ps1' -OutFile $env:USERPROFILE\Downloads\install_toast.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File $env:USERPROFILE\Downloads\install_toast.ps1

🐧 WSL Installation

For WSL/Linux environments (automatically handles Windows dependency)

👉 WSL Installation Guide

Quick install:

curl -fsSL 'https://gist.githubusercontent.com/ChrisColeTech/e621bf196dedc59276385c4f7d73c3aa/raw/c62c384d3302d76a710c04c3a6433e69bf370ef0/wsl_toast_install.sh' -o ~/install_toast_wsl.sh && bash ~/install_toast_wsl.sh

🍎 macOS Installation

For macOS environments (uses native AppleScript - no additional installs needed)

👉 macOS Installation Guide

Quick install:

curl -fsSL 'https://gist.githubusercontent.com/ChrisColeTech/[macos-install-script-url]' -o ~/install_toast_macos.sh && bash ~/install_toast_macos.sh

Quick Test

After installation, test with:

toast "Hello" "World"

Usage Examples

Basic Notifications

toast "Build Complete"
toast "Error" "Something went wrong"
toast "Long Running Task" "Your process has finished successfully"

Claude Code Integration

Perfect for Claude Code hooks! Add toast notifications to your Claude Code settings file to get notified of:

• Session starts/resumes
• Task completions
• Tool usage
• Errors requiring attention

See the installation guides for complete Claude Code configuration examples.

Claude Code Hook Configuration

Hooks are configured in JSON files with this structure:

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "toast 'Title' 'Message'",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Available Hook Events:

• PreToolUse - Before tool execution
• PostToolUse - After tool execution
• Notification - For notifications
• UserPromptSubmit - When user submits prompts
• Stop - When sessions stop
• SubagentStop - When subagents stop
• PreCompact - Before context compaction
• SessionStart - When sessions begin

Configuration Parameters:

• type: "command" (only supported type)
• command: Command to execute (e.g., toast "Title" "Message")
• timeout: Optional timeout in seconds
• matcher: Tool name pattern (exact, regex, or * wildcard)

Configuration Files:

• ~/.claude/settings.json (user-wide settings)
• .claude/settings.json (project-wide settings)
• .claude/settings.local.json (local project settings)

Temporarily Muting Hooks: To temporarily disable a specific hook:

1. Comment out the hook entry with // in the JSON file
2. Rename the event key (e.g., "PreToolUse" → "_PreToolUse")
3. Remove the hook entry temporarily

Note: Hooks are captured at startup, so restart Claude Code after making changes.

File Structure

windows-notifications/
├── README.md                      # Main overview (this file)
├── README-Windows.md              # Windows-specific installation guide
├── README-WSL.md                  # WSL-specific installation guide
├── README-macOS.md                # macOS-specific installation guide
├── windows_toast_install.ps1      # Local Windows installation script
├── windows_toast_uninstall.ps1    # Local Windows uninstallation script
├── wsl_toast_install.sh           # Local WSL installation script (with auto-dependency handling)
├── wsl_toast_uninstall.sh         # Local WSL uninstallation script
├── macos_toast_install.sh         # Local macOS installation script (native AppleScript)
└── macos_toast_uninstall.sh       # Local macOS uninstallation script

How It Works

Windows

• Uses BurntToast PowerShell module for native Windows notifications
• Creates toast.ps1 and toast.cmd in user bin directory
• Adds PowerShell aliases for easy access

WSL

• Automatically detects Windows username and installation
• Downloads and installs Windows dependency if needed
• Creates bash/zsh function that calls Windows PowerShell script
• Seamless integration between WSL and Windows notification system

macOS

• Uses native AppleScript (osascript) - no additional installs required
• Optional enhanced features with terminal-notifier or alerter
• Creates bash/zsh function for cross-platform compatibility
• Native macOS notification center integration

Requirements

Windows

• Windows 10/11
• PowerShell 5.1+
• Internet connection (for BurntToast module)

WSL

• Windows 10/11 with WSL installed
• Internet connection (for downloading dependencies)

macOS

• macOS 10.9+ (any reasonably recent version)
• No additional software required (uses built-in AppleScript)

Support

For issues or questions:

• Check the detailed installation guides: Windows | WSL | macOS
• Review troubleshooting sections in the installation guides
• Verify your environment meets the requirements listed above