Skip to content

NOTIFICATIONS.md

Latest commit

 

History

History
231 lines (170 loc) · 5.74 KB

NOTIFICATIONS.md

File metadata and controls

231 lines (170 loc) · 5.74 KB

Enhanced Notification System

The marchat client now features a comprehensive notification system that goes beyond simple bell notifications.

Features

1. Multiple Notification Modes

  • None: All notifications disabled
  • Bell: Terminal bell only (original behavior)
  • Desktop: Platform-specific desktop notifications for all messages
  • Both: Bell + desktop notifications for all messages

Note: When you set mode to desktop or both, it automatically enables notifications for all messages. If you only want notifications for @mentions, enable desktop mode and then use :bell-mention to restrict to mentions only.

2. Notification Levels

Messages are classified by priority:

  • Info: Regular chat messages
  • Mention: When someone @mentions you
  • DM: Direct messages (use :dm <user> <message> or :dm <user> to toggle DM mode)
  • Urgent: System alerts and critical messages

3. Desktop Notifications

Cross-platform support:

  • Linux: Uses notify-send (libnotify)
  • macOS: Uses osascript with AppleScript
  • Windows: Uses PowerShell toast notifications

Desktop notifications automatically:

  • Detect platform support at startup
  • Truncate long messages (100 chars max)
  • Rate limit to prevent spam (2 seconds between notifications)
  • Run asynchronously to avoid blocking

4. Smart Features

Quiet Hours

Disable notifications during specified hours:

:quiet 22 8        # Quiet from 10 PM to 8 AM
:quiet-off         # Disable quiet hours

Supports overnight ranges (e.g., 22:00 to 08:00).

Focus Mode

Temporarily disable all notifications:

:focus             # Default 30 minutes
:focus 1h          # 1 hour focus mode
:focus 2h30m       # 2 hours 30 minutes
:focus-off         # Disable focus mode

Mention-Only Mode

Only notify when someone @mentions you:

:bell-mention      # Toggle mention-only mode

Commands

Basic Notification Commands

Command Description
:bell Toggle bell notifications on/off
:bell-mention Toggle mention-only bell mode

Enhanced Notification Commands

Command Description
:notify-mode <mode> Set mode: none, bell, desktop, or both
:notify-desktop Toggle desktop notifications
:notify-status Show current notification settings
:quiet <start> <end> Enable quiet hours (24h format)
:quiet-off Disable quiet hours
:focus [duration] Enable focus mode (default 30m)
:focus-off Disable focus mode

Keyboard Shortcuts

Key Action
Alt+N Toggle desktop notifications

Configuration

Notification settings are automatically saved to your client config.json (same directory as profiles and themes: per-user app data, or MARCHAT_CONFIG_DIR; see README.md and ARCHITECTURE.md). Run marchat-client -doctor to confirm the resolved path. Example shape:

{
  "notification_mode": "bell",
  "desktop_notifications": false,
  "desktop_on_mention": true,
  "desktop_on_dm": true,
  "desktop_on_all": false,
  "quiet_hours_enabled": false,
  "quiet_hours_start": 22,
  "quiet_hours_end": 8,
  "enable_bell": true,
  "bell_on_mention": false
}

Usage Examples

Setup Desktop Notifications

# Enable desktop notifications
:notify-mode desktop

# Or enable both bell and desktop
:notify-mode both

# Toggle desktop notifications with hotkey
Alt+N

Configure Quiet Hours

# No notifications from 10 PM to 8 AM
:quiet 22 8

# No notifications during work hours (9 AM - 5 PM)
:quiet 9 17

# Disable quiet hours
:quiet-off

Use Focus Mode

# Quick focus (30 minutes)
:focus

# Extended focus session
:focus 2h

# Exit focus mode early
:focus-off

Check Notification Status

:notify-status

# Output example:
# Mode: both | Bell: true (mention-only: false) | Desktop: true (supported: true) | Quiet hours: 22:00 - 08:00

Platform Requirements

Linux

  • Desktop notifications: Requires libnotify (notify-send) 
    # Ubuntu/Debian
sudo apt install libnotify-bin

# Fedora/RHEL
sudo dnf install libnotify

# Arch
sudo pacman -S libnotify

macOS

  • Desktop notifications: Built-in osascript (no installation needed)

Windows

  • Desktop notifications: Built-in PowerShell (no installation needed)

Backward Compatibility

The new system maintains full backward compatibility:

  • Existing :bell and :bell-mention commands work as before
  • Legacy config settings (enable_bell, bell_on_mention) are preserved
  • Default mode is bell (original behavior)

Implementation Details

Rate Limiting

  • Bell: Minimum 500ms between notifications
  • Desktop: Minimum 2 seconds between notifications

Notification Logic

  1. Check if notifications are enabled (mode != none)
  2. Check quiet hours and focus mode
  3. Determine notification level based on message content
  4. Apply user preferences (mention-only, desktop-only, etc.)
  5. Send appropriate notifications (bell and/or desktop)

Thread Safety

The NotificationManager uses mutex locks to ensure thread-safe operation:

  • Safe for concurrent notification calls
  • Configuration updates are atomic

Testing

Run tests with:

go test ./client -v -run TestNotificationManager

The test suite covers:

  • Manager initialization
  • Mode switching
  • Bell and desktop toggle
  • Quiet hours configuration
  • Focus mode
  • Notification sending (all levels)

Future Enhancements

Potential future additions:

  • Per-user notification rules
  • Custom notification sounds
  • Notification history/log
  • Priority-based notification filtering
  • Integration with system Do Not Disturb
  • Notification action buttons (reply, dismiss, etc.)