scitex-notification 0.1.1

Multi-backend notification system for SciTeX

SciTeX Notification (scitex-notification)

Multi-backend notification system for scientific workflows

Full Documentation · pip install scitex-notification

---

Problem

You delegate a task to an AI coding agent — or kick off a build, training run, deploy — and then you wait. You stare at the terminal, or you context-switch to something else and forget to check back. Either way, you lose: polling kills focus, and forgetting wastes hours.

The same problem scales across every long-running process: CI/CD pipelines, HPC jobs, data migrations, batch processing. There is no standard way to route "I'm done" across the channels developers actually use — TTS, phone calls, SMS, Slack, email.

Solution

SciTeX Notification provides a unified alert interface across 8 backends with a single function call. It speaks, calls, texts, and pings — so you never miss a completion or failure.

Backend	API	Transport	Cost	Internet	Notes
Audio	alert()	TTS to local speakers	Free	No	Via scitex-audio; SSH relay supported
Desktop	alert()	notify-send / PowerShell	Free	No	Linux / WSL
Emacs	alert()	emacsclient message	Free	No	Popup, minibuffer, or alert
Matplotlib	alert()	Visual popup window	Free	No
Playwright	alert()	Browser popup	Free	No
Email	alert()	SMTP	Free	Required	Gmail, SMTP relay
Webhook	alert()	HTTP POST	Free	Required	Slack, Discord, custom endpoints
Twilio	call() sms()	Phone call / SMS	Paid	Required	No SDK — stdlib urllib only

alert() tries backends in fallback order until one succeeds. call() and sms() target Twilio directly.

Auditory Feedback -> Phone Call Escalation

When an AI agent needs your attention — even while you sleep — it can escalate from audio to phone call.

   

Fig. 1: Left — Claude Code terminal showing audio → phone call escalation after 7 consecutive auditory feedback but without no response from user. Right — iPhone receiving repeated "SciTeX Alert" calls from the AI agent.

Penetrating iPhone Silent Mode:

1. Emergency Bypass (most reliable): Save your Twilio number as a contact → Ringtone → enable Emergency Bypass. All calls ring regardless of Focus/Silent mode.
2. Repeated Calls (fallback): iOS allows the second call from the same number within 3 minutes to ring through. repeat=2 triggers this automatically with a 30-second gap.

Example: /speak-and-continue Command in Claude Code

The /speak-and-continue command is a real-world example of scitex-notification in action. It configures an AI coding agent (Claude Code) to:

1. Provide TTS feedback via audio_speak MCP tool while working autonomously
2. Repeat the same audio message when the user sends /speak-and-continue again (they may be away)
3. Count consecutive speaks without user response (spoke counter)
4. Escalate to phone call after 7 unanswered speaks — waking the user if asleep

This enables a 24/7 development workflow: the agent works autonomously, speaks progress aloud, and calls your phone when it needs your attention or when all tasks are complete.

Installation

Requires Python >= 3.10.

pip install scitex-notification

Install with optional backends:

pip install "scitex-notification[audio]"    # audio alerts via scitex-audio
pip install "scitex-notification[twilio]"   # SMS via Twilio
pip install "scitex-notification[mcp]"      # MCP server for AI agents
pip install "scitex-notification[all]"      # everything

SciTeX users: pip install scitex already includes Notification. Alerts are automatic via @scitex.session.

Quickstart

import scitex_notification as notification

# Alert via default backend (audio → emacs → email fallback)
notification.alert("Training complete. Val loss: 0.042")

# Alert via a specific backend
notification.alert("Job finished", backend="email")

# Alert via multiple backends
notification.alert("Critical failure", backend=["sms", "email"])

# Make a phone call via Twilio
notification.call("Critical alert!", repeat=2,  # Calls twice to bypass silent mode)

# Send an SMS via Twilio
notification.sms("Build done!")

Configure backends via environment variables (see .env.example):

export SCITEX_NOTIFY_DEFAULT_BACKEND=audio
export SCITEX_NOTIFY_TWILIO_SID=ACxxxxxxx
export SCITEX_NOTIFY_TWILIO_TOKEN=...
export SCITEX_NOTIFY_TWILIO_TO=+XX-XXX-XXX-XXXX

Three Interfaces

Python API

import scitex_notification as notification

notification.alert("Job done")                           # default backend (with fallback)
notification.alert("Error", backend="email")             # specific backend
notification.alert("Critical", backend=["sms", "email"]) # multiple backends
notification.call("Urgent!")                             # phone call via Twilio
notification.sms("Build done!")                          # SMS via Twilio
notification.available_backends()                        # list installed backends

Full API reference

CLI Commands

scitex-notification --help                       # Show all commands
scitex-notification send "Job done"              # Send via default backend
scitex-notification send "Done" --backend email  # Send via specific backend
scitex-notification config                       # Show configuration
scitex-notification backends                     # List available backends
scitex-notification mcp list-tools              # List MCP tools

Full CLI reference

MCP Server — for AI Agents

AI agents can send notifications and check system status autonomously.

Tool	Description
notify_handler	Send an alert via specified or fallback backends
notify_by_level_handler	Send alert using level-based backend config
list_backends_handler	List all backends with availability status
get_config_handler	Show current notification configuration

scitex-notification mcp start

Add .mcp.json to your project root. Use SCITEX_NOTIFICATION_ENV_SRC to load all configuration from a .src file — this keeps .mcp.json static across environments:

{
  "mcpServers": {
    "scitex-notification": {
      "command": "scitex-notification",
      "args": ["mcp", "start"],
      "env": {
        "SCITEX_NOTIFICATION_ENV_SRC": "${SCITEX_NOTIFICATION_ENV_SRC}"
      }
    }
  }
}

Full MCP specification

Centralize Speakers by SSH Audio Relay

Running jobs on a remote server or NAS? TTS alerts are relayed back through your SSH tunnel to the speakers on your desk — your remote code speaks through your local machine.

# On your local machine (has speakers)
scitex-audio relay start

# In your SSH config (~/.ssh/config)
Host myserver
    RemoteForward 31293 127.0.0.1:31293

# On the remote server — audio plays on your local speakers
notify.alert("Training complete. Val loss: 0.042")

No extra configuration on the notification side. The scitex-audio relay handles the routing automatically.

pip install "scitex-notification[audio]"

Part of SciTeX

SciTeX Notification is part of SciTeX.

The SciTeX system follows the Four Freedoms for Research below, inspired by the Free Software Definition:

Four Freedoms for Research

0. The freedom to run your research anywhere — your machine, your terms.
1. The freedom to study how every step works — from raw data to final manuscript.
2. The freedom to redistribute your workflows, not just your papers.
3. The freedom to modify any module and share improvements with the community.

AGPL-3.0 — because we believe research infrastructure deserves the same freedoms as the software it runs on.

---