Metadata-Version: 2.4
Name: rundone
Version: 1.0.0
Summary: Your terminal's gentle nudge. Get native notifications when commands finish.
License: MIT
Project-URL: Homepage, https://github.com/rundone/rundone
Project-URL: Issues, https://github.com/rundone/rundone/issues
Keywords: terminal,notification,cli,colab,jupyter,productivity
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Utilities
Classifier: Framework :: Jupyter
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: win10toast; sys_platform == "win32"
Dynamic: license-file

# 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

```bash
pip install rundone
```

## Terminal usage

Prefix any command with `rundone`:

```bash
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
```

```bash
# 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

```python
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)

```python
import rundone
rundone.load_magic()
```

Then in any cell:

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

### 3. Decorator (wrap a function)

```python
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:

```python
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
