Kilo-Org_kilo/packages/kilo-docs/docs/features/system-notifications.md

System Notifications

System notifications are native operating system notifications that appear in your system's notification center or tray. Unlike VSCode's built-in notifications that only appear within the editor, system notifications are visible even when:

• VSCode is minimized or in the background
• You're working in other applications
• Your screen is locked (depending on OS settings)
• You're away from your computer

Kilo Code uses system notifications to inform you about:

• Task completion status
• Important errors or warnings
• Long-running operation updates
• Critical system events

Supported Operating Systems

Kilo Code's system notifications work on all major operating systems with different underlying technologies:

Operating System	Technology	Requirements
macOS	AppleScript + terminal-notifier	Built-in support, optional enhanced features
Windows	PowerShell + Windows Runtime	PowerShell execution policy configuration
Linux	notify-send	libnotify package installation

Platform-Specific Setup

macOS Setup

macOS has the best built-in support for system notifications with two available methods:

Method 1: Built-in AppleScript (Fallback)

No additional setup required. Kilo Code uses macOS's built-in command to display notifications.

Method 2: Enhanced with terminal-notifier (Recommended)

For enhanced notifications with custom icons, install terminal-notifier:

# Install via Homebrew
brew install terminal-notifier

# Or install via npm
npm install -g terminal-notifier

How it works: Kilo Code first attempts to use terminal-notifier and automatically falls back to AppleScript if it's not installed.

Windows Setup

Windows notifications require PowerShell execution policy configuration to work properly.

Step 1: Configure PowerShell Execution Policy

Open PowerShell as Administrator and run:

# Check current execution policy
Get-ExecutionPolicy

# Set execution policy to allow local scripts
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Step 2: Verify Windows Runtime Access

Windows notifications use the Windows.UI.Notifications API through PowerShell. This is available on:

• ✅ Windows 10 (all versions)
• ✅ Windows 11 (all versions)
• ✅ Windows Server 2016 and later
• ❌ Windows 8.1 and earlier (limited support)

Execution Policy Options

Policy	Description	Security Level	Recommended
Restricted	No scripts allowed (default)	Highest	❌ Blocks notifications
RemoteSigned	Local scripts run, downloaded need signing	High	✅ Recommended
Unrestricted	All scripts run with warnings	Medium	⚠️ Use with caution
AllSigned	All scripts must be signed	Highest	❌ Too restrictive

Linux Setup

Linux notifications require the libnotify package and notify-send command.

Ubuntu/Debian Installation

# Install libnotify
sudo apt update
sudo apt install libnotify-bin

# Verify installation
which notify-send

Red Hat/CentOS/Fedora Installation

# RHEL/CentOS
sudo yum install libnotify

# Fedora
sudo dnf install libnotify

# Verify installation
which notify-send

Arch Linux Installation

# Install libnotify
sudo pacman -S libnotify

# Verify installation
which notify-send

Desktop Environment Requirements

System notifications work best with these desktop environments:

Desktop Environment	Support Level	Notes
GNOME	✅ Full support	Native notification center
KDE Plasma	✅ Full support	Native notification system
XFCE	✅ Good support	Requires notification daemon
Unity	✅ Full support	Ubuntu's notification system
i3/Sway	⚠️ Limited	Requires manual notification daemon setup
Headless	❌ No support	No display server available

Notification Daemon Setup (Advanced)

For minimal window managers, you may need to start a notification daemon:

# Install and start dunst (lightweight notification daemon)
sudo apt install dunst  # Ubuntu/Debian
sudo pacman -S dunst    # Arch Linux

# Start dunst manually
dunst &

# Or add to your window manager startup script
echo "dunst &" >> ~/.xinitrc

Verifying System Notifications

Test Commands by Platform

macOS Test

# Test AppleScript method
osascript -e 'display notification "Test message" with title "Test Title" sound name "Tink"'

# Test terminal-notifier (if installed)
terminal-notifier -message "Test message" -title "Test Title" -sound Tink

Windows Test

# Test PowerShell notification
$template = @"
<toast>
    <visual>
        <binding template="ToastText02">
            <text id="1">Test Title</text>
            <text id="2">Test message</text>
        </binding>
    </visual>
</toast>
"@

[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
$xml = New-Object Windows.Data.Xml.Dom.XmlDocument
$xml.LoadXml($template)
$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Test App").Show($toast)

Linux Test

# Test notify-send
notify-send "Test Title" "Test message"

# Test with icon (optional)
notify-send -i dialog-information "Test Title" "Test message"

Troubleshooting

Common Issues and Solutions

macOS Issues

Problem: Notifications not appearing

• Solution 1: Check System Preferences → Notifications → Terminal (or VSCode) → Allow notifications
• Solution 2: Verify Do Not Disturb is disabled
• Solution 3: Test with the manual commands above
• Solution 4: Ensure terminal-notifier is properly installed: brew install terminal-notifier

Windows Issues

Problem: "Execution of scripts is disabled" error

• Solution: Configure PowerShell execution policy as described in setup
• Command: Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem: Notifications not appearing in Windows 11

• Solution 1: Check Settings → System → Notifications → Allow notifications
• Solution 2: Ensure Focus Assist is not blocking notifications
• Solution 3: Verify Windows notification service is running

Problem: PowerShell script errors

• Solution: Update PowerShell to version 5.1 or later
• Check version: $PSVersionTable.PSVersion

Linux Issues

Problem: notify-send: command not found

• Solution: Install libnotify package for your distribution
• Ubuntu/Debian: sudo apt install libnotify-bin
• RHEL/CentOS: sudo yum install libnotify
• Arch: sudo pacman -S libnotify

Problem: Notifications not appearing in minimal window managers

• Solution: Install and configure a notification daemon like dunst
• Install: sudo apt install dunst (Ubuntu/Debian)
• Start: dunst &

Problem: Permission denied errors

• Solution: Ensure your user has access to the display server
• Check: echo $DISPLAY should return something like :0