Notifications Overview

All outbound notifications from Luci go through ~/workspace/notify.py -- a lightweight Telegram helper with quiet hours, deduplication, and forum topic routing.

Architecture

• Single module: notify.py (~120 lines) with no external dependencies beyond stdlib
• Transport: Telegram Bot API via urllib.request (no SDK needed)
• Two destinations:
• Elmar DM (chat_id 246672479) -- direct private messages
• Claude Forum group (chat_id -1003838721412) -- organized by topic threads

Forum Topics

The Claude Forum is a Telegram group with forum mode enabled. Each topic is a persistent thread:

Sending Functions

from notify import send, send_telegram, send_to_topic, send_life_manager, send_home, send_work, send_mc, send_spotify, send_ticket_notification, send_audio

# Preferred: central dispatcher with named destination key
send("dm", "message")
send("home", "message")
send("work", "message")
send("mc", "message")
send("life-manager", "message")
send("general", "message")

# Audio upload (sendAudio multipart)
send_audio("work", "/path/to/file.mp3", caption="Daily brief")

# Lower-level / legacy wrappers (still supported)
send_telegram("message")            # DM to Elmar
send_to_topic(TOPIC_LIFE_MANAGER, "message")
send_life_manager("message")
send_home("message")
send_work("message")
send_mc("message")
send_spotify("message")

# MC ticket notification (auto-formats with priority emoji and link)
send_ticket_notification(ticket_id, identifier, title, priority="medium")

NOTIFY_DESTINATIONS — single source of truth

notify.py exposes a NOTIFY_DESTINATIONS dict mapping each key to (chat_id, thread_id, label). This is the canonical list — add new topics here and every consumer (CLI, MC dropdown, scheduler tasks) sees them automatically. Valid keys: dm, general, home, life-manager, work, mc.

Per-task routing — notify_to: frontmatter

Scheduled tasks declare a destination in their .md frontmatter:

---
id: my-task
notify_to: home   # one of NOTIFY_DESTINATIONS keys
...
---

The scheduler injects this as LUCI_NOTIFY_DEST into the task subprocess environment. Scripts that route through notify.py read it (os.environ.get("LUCI_NOTIFY_DEST", <default>)) to pick the destination. Falls back to a per-script default when unset.

CLI

python3 ~/workspace/notify.py "msg"                # DM to Elmar
python3 ~/workspace/notify.py --dest work "msg"    # Forum: Work topic
python3 ~/workspace/notify.py --dest mc "msg"

--topic is accepted as a legacy alias for --dest.

Quiet Hours

• Window: 21:00 -- 06:00 SAST
• Behavior: Messages sent during quiet hours are silently dropped (return False)
• Override: Pass force=True to bypass quiet hours
• Auto-forced: Critical/high priority ticket notifications and task suspension alerts always bypass quiet hours

Deduplication

• Mechanism: Hash-based dedup stored in /tmp/luci-notify-dedup.json
• Window: 1 hour -- identical messages within 60 minutes are suppressed
• Cleanup: Entries older than 2 hours are pruned on each send
• Bypass: force=True skips dedup entirely

Notification Types

Scheduler Notifications

The 03-scheduler/overview|scheduler sends notifications based on each task's notify_on setting:

MC Ticket Notifications

Created via send_ticket_notification():

• Routes to the Mission Control forum topic
• Includes priority emoji (red/yellow/blue/white circle)
• Links to the MC dashboard ticket page
• Critical and high priority tickets force-send (bypass quiet hours)

CLI Usage

python3 notify.py "Your message here"

Sends a direct DM to Elmar with force=True (bypasses quiet hours and dedup). Useful for manual one-off alerts.

Parse Mode

All messages default to Markdown parse mode (parse_mode="Markdown"). Pass parse_mode=None to send plain text if Markdown formatting causes issues.

Error Handling

• Send failures are caught and printed to stdout (Telegram send failed: {error})
• Failed sends return False but do not raise exceptions
• The 10-second timeout on HTTP requests prevents hangs

Related

• 03-scheduler/overview -- Task failure notifications
• 02-mission-control/overview -- Ticket creation triggers MC topic notifications
• 10-health-and-ops/overview -- Health check alerts route through notify.py

Key Takeaways

• All notifications flow through a single notify.py module using the Telegram Bot API
• Messages are routed to either Elmar's DM or one of 5 forum topics in the Claude Forum group
• Quiet hours (21:00--06:00 SAST) suppress non-critical notifications; force=True overrides
• Deduplication prevents the same message from being sent more than once per hour
• Critical events (task suspension, scheduler crash, probation failure) always bypass quiet hours
• The module is intentionally simple -- no external dependencies, no retry logic, no queue