Windows Toast Notifications - Windows Installation Guide with Claude Code integration

README-Windows.md

Windows Toast Notifications - Windows Installation

This guide covers installing toast notifications for Windows PowerShell/CMD environments.

Important: Claude Code Settings Backup & Replace

⚠️ CRITICAL INFORMATION: This installer will automatically backup and replace your existing Claude Code hook configuration.

What Happens to Your Settings:

• ✅ Automatic Backup: Your existing .claude/settings.json is backed up with a timestamp
• ✅ Non-Hook Settings Preserved: Model preferences, API keys, etc. are kept
• ⚠️ Hooks Are Replaced: Any existing Claude Code hooks will be replaced with toast notification hooks
• 📍 Backup Location: C:\Users\[YourUsername]\.claude\settings.json.backup_YYYYMMDD_HHMMSS

Why Replace Instead of Merge:

• Predictable behavior - You know exactly what hooks are active
• No conflicts - Prevents duplicate or conflicting hook configurations
• Clean installation - Ensures toast notifications work optimally
• Easy troubleshooting - Clear hook configuration for debugging

If You Have Existing Hooks:

1. Your hooks will be backed up automatically before installation
2. Toast notification hooks will replace them for optimal functionality
3. To restore your old hooks: Copy from the backup file after installation
4. To merge hooks manually: Edit the settings.json file after installation

---

Quick Installation

Step 1: Download and Install Toast Notifications

1. Open PowerShell as a normal user (no admin rights required)

2. Download the installation script:

   curl.exe -fsSL 'https://gist.githubusercontent.com/ChrisColeTech/1f79919c60bf210982a04bc607a1a1d7/raw/windows_toast_install.ps1' -o install_toast.ps1

3. Execute the installation script:

   powershell -NoProfile -ExecutionPolicy Bypass -File install_toast.ps1

4. Wait for the "Setup complete" message

5. Close and re-open your terminal for PATH and profile changes to take effect

Step 2: Test the Installation

toast "Hello" "This is a test"

If you see a Windows toast notification, the installation was successful!

What Gets Installed

• BurntToast PowerShell module - Handles creating Windows notifications
• toast.ps1 - PowerShell script in %USERPROFILE%\bin\
• toast.cmd - CMD wrapper in %USERPROFILE%\bin\
• PATH update - Adds %USERPROFILE%\bin\ to your user PATH
• PowerShell profile - Adds toast and t aliases

Usage Examples

Basic Notifications

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

PowerShell Aliases

# Full command
toast "Title" "Body"

# Short alias
t "Quick notification"

Claude Code Integration

Settings File Location

C:\Users\[YourUsername]\.claude\settings.json

Complete Hook Configuration

{
  "model": "sonnet",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"New session started - Ready to help!\""
          }
        ]
      },
      {
        "matcher": "resume",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Session resumed - Continuing where we left off\""
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Processing your request...\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Executing bash command\""
          }
        ]
      },
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Starting specialized task agent\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"File created successfully\""
          }
        ]
      },
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"File edited successfully\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"⚠️ User input needed to continue\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"✅ Task completed successfully\""
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"🤖 Subagent task finished\""
          }
        ]
      }
    ]
  }
}

Hook Types Explained

Hook Type	When It Triggers	Purpose
SessionStart	New session or resume	Welcome notifications
UserPromptSubmit	When you send a message	Confirms input received
PreToolUse	Before tool execution	Shows what's about to happen
PostToolUse	After successful tool use	Confirms completion
Notification	Claude needs permission or idle timeout	Attention alerts
Stop	Main agent finishes responding	Task completion
SubagentStop	Specialized agent finishes	Subtask completion

Minimal Configuration

For a simpler setup, use just the essential hooks:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Task complete\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command", 
            "command": "toast \"Claude Code\" \"Input needed\""
          }
        ]
      }
    ]
  }
}

Critical Configuration

For the most important notifications, use these critical hooks:

{
  "model": "sonnet",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"New session started - Ready to help!\""
          }
        ]
      },
      {
        "matcher": "resume",
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Session resumed - Continuing where we left off\""
          }
        ]
      }
    ],
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"⚠️ User input needed to continue\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"✅ Task completed successfully\""
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"🤖 Subagent task finished\""
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"📝 Compacting context to continue\""
          }
        ]
      }
    ]
  }
}

Managing Hooks

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 (PowerShell compatible on Windows)
• timeout: Optional timeout in seconds
• matcher: Tool name pattern (exact, regex, or * wildcard)

Configuration Files (in order of precedence):

• .claude/settings.local.json (local project settings)
• .claude/settings.json (project-wide settings)
• C:\Users\[YourUsername]\.claude\settings.json (user-wide settings)

Temporarily Muting Hooks: To temporarily disable specific hooks:

1. Comment out: Add // before the hook entry in JSON
2. Rename event: Change "PreToolUse" to "_PreToolUse"
3. Remove temporarily: Delete the hook entry

Example of commenting out a hook:

{
  "hooks": {
    // "PreToolUse": [
    //   {
    //     "matcher": "Bash",
    //     "hooks": [
    //       {
    //         "type": "command",
    //         "command": "toast \"Claude Code\" \"Executing bash command\""
    //       }
    //     ]
    //   }
    // ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "toast \"Claude Code\" \"Task complete\""
          }
        ]
      }
    ]
  }
}

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

Uninstallation

Automated Uninstall

curl.exe -fsSL 'https://gist.githubusercontent.com/ChrisColeTech/c7c8d4fb8f8e72ac01722cb5d5ce79f9/raw/windows_toast_uninstall.ps1' -o uninstall_toast.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File uninstall_toast.ps1

Manual Uninstall

1. Remove %USERPROFILE%\bin\toast.ps1 and %USERPROFILE%\bin\toast.cmd
2. Remove %USERPROFILE%\bin\ from your user PATH
3. Remove toast functions from your PowerShell profile
4. Optionally: Uninstall-Module -Name BurntToast -Force

Troubleshooting

"BurntToast module not found"

• Ensure PowerShell execution policy allows module installation
• Try running PowerShell as Administrator
• Manually install: Install-Module -Name BurntToast -Scope CurrentUser

"PowerShell execution policy" errors

• Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
• Or use: powershell -ExecutionPolicy Bypass -File script.ps1

"toast command not found"

• Restart your terminal for PATH changes to take effect
• Verify %USERPROFILE%\bin\ is in your PATH
• Check that toast.cmd exists in %USERPROFILE%\bin\

Requirements

• Windows 10/11
• PowerShell 5.1 or later
• Internet connection for BurntToast module installation
• User-level permissions (no admin required)

Next Steps

• For WSL Integration: See README-WSL.md for WSL setup
• For Development: Check out the local scripts in this directory