rundone 1.0.0

Your terminal's gentle nudge. Get native notifications when commands finish.

Rundone

Your terminal's gentle nudge.

Get a native notification when any command finishes — whether you're in a terminal, Colab, Kaggle, or Jupyter.

Install

pip install rundone

Terminal usage

Prefix any command with rundone:

rundone python train.py --epochs 100
rundone pip install torch
rundone make build
rundone pytest tests/ -v

Switch to another app — when it's done, a notification slides in:

✓ train.py finished — 20m 34s

Options

--quiet, -q       Suppress rundone's terminal output (notification still fires)
--title, -t       Custom notification title (default: "Rundone")
--min-time, -m    Only notify if command took longer than N seconds

# Only notify for long commands
rundone --min-time 30 python train.py

# Custom title
rundone --title "Model Training" python train.py

# Silent mode
rundone --quiet make build

Colab / Kaggle / Jupyter usage

Three ways to use Rundone in notebooks:

1. One-liner at the end of a cell

import rundone

# Your long-running code
model.fit(X_train, y_train, epochs=100)

# This line sends a browser notification
rundone.notify("Training complete!")

2. Cell magic (wrap an entire cell)

import rundone
rundone.load_magic()

Then in any cell:

%%rundone
model.fit(X_train, y_train, epochs=100)
# Notification fires automatically when the cell finishes

3. Decorator (wrap a function)

import rundone

@rundone.timer_notify
def train_model():
    model.fit(X_train, y_train, epochs=100)

train_model()  # notification fires when function returns

Enable browser notifications

The first time you use Rundone in a notebook, your browser will ask for notification permission. You can also run this to trigger the prompt:

rundone.enable_notifications()

Cross-platform support

Environment	Notification method	Extra dependencies
macOS terminal	osascript (native)	None
Linux terminal	notify-send (libnotify)	None*
Windows terminal	win10toast / PowerShell	Auto-installed
Colab / Kaggle	Browser notification	None
Jupyter	Browser notification	None

*Most Linux desktops include notify-send. If not: sudo apt install libnotify-bin

How it works

Terminal: Rundone wraps your command, streams all output normally, and fires a native OS notification when it exits. Your command runs exactly as it would without Rundone — zero overhead.

Notebooks: Rundone uses the browser's Notification API to send a popup even when you're in another tab. It also shows an inline banner in the cell output.

Exit codes

Rundone preserves your command's exit code. If your script exits with code 1, rundone exits with code 1 too. Works seamlessly in shell scripts and CI.

License

MIT