Codex Notify for WSL

Windows toast notifications for Codex running in WSL. Never miss an approval prompt again.

Features

• Windows toast notifications when Codex needs approval
• Configurable notification types (approval, success, error, long-running)
• Multiple notification methods with automatic fallback
• Simple configuration file
• Minimal dependencies

Installation

npm (Recommended)

npm install -g codex-notify-wsl

Manual Installation

git clone https://github.com/yourusername/codex-notify-wsl.git
cd codex-notify-wsl
npm install
npm link

Quick Setup

1. Install a Windows notification tool (choose one):

   BurntToast (Recommended):

   # PowerShell Admin
   Install-Module -Name BurntToast -Force

   SnoreToast: Download from GitHub and place in C:\Windows\System32

2. Reload your shell:

   source ~/.bashrc

3. Test notifications:

   codex-notify test all

Usage

# Use Codex with notifications
codex "your prompt"

# Without notifications
codex-silent "your prompt"

# Direct Codex (bypass wrapper)
codex-real "your prompt"

Configuration

Configuration file: ~/.codex/notify.env

# Edit configuration
codex-notify config

# Or edit directly
nano ~/.codex/notify.env

Configuration Options

# Core Settings
NOTIFY_ENABLED=true          # Enable/disable all notifications
NOTIFY_METHOD=auto          # auto, burnttoast, snoretoast, msg, bell
NOTIFY_SOUNDS=true          # Play sounds
NOTIFY_PERSISTENT=false     # Keep notifications until dismissed
NOTIFY_DEBUG=false          # Verbose logging

# Event Triggers
NOTIFY_ON_APPROVAL=true     # Approval prompts
NOTIFY_ON_SUCCESS=true      # Task completion
NOTIFY_ON_ERROR=true        # Errors
NOTIFY_ON_LONG_RUN=true     # Long-running tasks (>60s)

# Customization
LONG_TASK_THRESHOLD=60      # Seconds before "long-running" alert
CUSTOM_PATTERNS=""          # Pipe-separated custom patterns
USE_EMOJIS=true            # Visual emojis in titles
NOTIFICATION_COOLDOWN=2     # Min seconds between notifications

Environment Variable Overrides

Override any setting via environment variables:

# Disable for one command
CODEX_NOTIFY_ENABLED=false codex "your prompt"

# Force specific method
CODEX_NOTIFY_METHOD=burnttoast codex "your prompt"

# Debug mode
CODEX_NOTIFY_DEBUG=true codex "your prompt"

Testing

# Test all notification types
codex-notify test all

# Test specific types
codex-notify test approval
codex-notify test success
codex-notify test error

Troubleshooting

No notifications appearing

1. Check Windows Focus Assist settings

   • Open Windows Settings → System → Focus assist
   • Ensure it's set to "Off" or configure priority list

2. Verify notification tool is installed

   # Check BurntToast
   Get-Module -ListAvailable -Name BurntToast
   
   # Check SnoreToast
   Test-Path "C:\Windows\System32\snoretoast.exe"

3. Check WSL integration

   # Verify PowerShell access from WSL
   powershell.exe -Command "echo 'PowerShell works'"
   
   # Check if running in WSL
   grep -qi microsoft /proc/version && echo "WSL detected"

4. Review logs

   # Check recent notifications
   tail -f ~/.codex/notifications.log
   
   # Check for errors
   grep ERROR ~/.codex/notifications.log

5. Test notification methods directly

   # Test each method
   CODEX_NOTIFY_METHOD=burnttoast codex-notify test approval
   CODEX_NOTIFY_METHOD=snoretoast codex-notify test approval
   CODEX_NOTIFY_METHOD=msg codex-notify test approval

Common Issues

WSL-Specific Issues

1. PowerShell execution policy

   # Run in Windows PowerShell as Administrator
   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

2. Path issues

   # Ensure Windows paths are accessible
   echo $PATH | grep -q "/mnt/c" || echo "Windows paths not in PATH"

3. Permission denied

   # Make scripts executable
   chmod +x ~/.local/bin/codex-notify
   chmod +x ~/.codex/notify.py

How It Works

The wrapper script monitors Codex output for specific patterns:

• "approval requested", "waiting for permission" → Approval notification
• "task complete", "finished successfully" → Success notification
• "error occurred", "failed" → Error notification
• Tasks >60 seconds → Long-running notification

Requirements

• WSL 2 on Windows 10/11
• Codex CLI
• PowerShell access from WSL
• BurntToast or SnoreToast (optional but recommended)

Files

codex-notify         # Main wrapper script
.env.example        # Configuration template
install.sh          # Installation script
README.md          # This file

Uninstallation

To completely remove Codex Notify:

# Uninstall npm package
npm uninstall -g codex-notify-wsl

# Remove configuration
rm -f ~/.codex/notify.env
rm -f ~/.codex/notify.py
rm -f ~/.codex/notifications.log*

# Remove aliases from shell config
# Edit ~/.bashrc or ~/.zshrc and remove the Codex Notify section

FAQ

Q: Can I use this without WSL? A: No, this tool is specifically designed for WSL environments. For native Windows, use Windows notification APIs directly.

Q: Does this work with WSL 1? A: It should work but WSL 2 is recommended for better Windows integration.

Q: Can I customize notification icons? A: Currently limited to what BurntToast/SnoreToast provide. Custom icons may be added in future versions.

Q: Why aren't notifications showing in Action Center? A: Ensure NOTIFY_PERSISTENT is set to true and you're using BurntToast.

Q: Can I use this with other CLI tools? A: Yes, the wrapper pattern can be adapted for any CLI tool that outputs to stdout/stderr.

Q: How do I disable notifications temporarily? A: Set CODEX_NOTIFY_ENABLED=false or use the codex-silent alias.

Contributing

Pull requests welcome. Please test changes with both BurntToast and fallback methods. See CONTRIBUTING.md for details.

License

MIT - See LICENSE file for details.

Changelog

See CHANGELOG.md for version history.

Support

For issues and feature requests, please use the GitHub issues page.