WhenDone Plus
Automatically notify when long-running commands complete.
How It Works
- User runs a long command (e.g.
npm test, docker build, git push)
- The agent monitors the command execution time
- If the command runs longer than the threshold (default 10s), the agent notifies the user on completion
- Exit code is passed through
Workflow
Step 1: Detect long-running command
Identify commands likely to exceed threshold:
npm test, npm run test, npx playwright testdocker build, docker compose up, docker compose downgit push, git pull, git clonepip install, npm install, pnpm install, yarn installcargo build, cargo test, go build, dotnet build- Custom scripts, database migrations, data processing pipelines
ffmpeg, rsync, scp, large file transfers
Step 2: Monitor execution
Start a background timer when the command begins. Track:
- Elapsed wall-clock time
- Peak memory usage (if available)
- Child process tree (for pipeline awareness)
Step 3: Notify on completion
Basic notification format:
✅ "Command finished: npm test completed in 142s (exit 0)"
❌ "Command finished: docker build failed in 89s (exit 1)"
Include:
- Command name (first word + key args)
- Execution time (rounded to seconds)
- Exit code (success/failure)
- Optional: memory peak, output file path if redirected
Step 4: Handle edge cases
- Commands completing under 10s: no notification (too fast to matter)
- Interactive/TUI commands (vim, nano, htop): skip (user is watching)
- Piped commands (e.g.
npm test | grep error): monitor the pipeline, not the first process
- Backgrounded commands (
&): notify on background process completion
- Chained commands (
;): notify per-segment or in aggregate
- Commands killed by signal: notify with signal name (e.g. "killed by SIGTERM")
Notification Mechanisms
Windows Toast Notification (PowerShell)
Add-Type -AssemblyName System.Windows.Forms
$balloon = New-Object System.Windows.Forms.NotifyIcon
$balloon.Icon = [System.Drawing.SystemIcons]::Information
$balloon.BalloonTipTitle = "Command Complete"
$balloon.BalloonTipText = "npm test finished in 142s (exit 0)"
$balloon.Visible = $true
$balloon.ShowBalloonTip(5000)
Start-Sleep -Seconds 5
$balloon.Dispose()
Terminal Bell (cross-platform)
echo -e "\a" # ASCII bell character
printf '\a' # POSIX
BurntToast Module (Windows 10/11)
Import-Module BurntToast
New-BurntToastNotification -Text "Command Complete", "npm test finished in 142s (exit 0)"
macOS Notification
osascript -e 'display notification "npm test finished in 142s" with title "Command Complete"'
terminal-notifier -title "Command Complete" -message "npm test finished in 142s"
Linux Notification (notify-send)
notify-send "Command Complete" "npm test finished in 142s"
Error Handling
| Error |
Cause |
Fix |
| Notification never fires |
Command completed under threshold |
Expected. Threshold is 10s by default. |
| Wrong exit code reported |
Shell pipeline masking failures |
Use $PIPESTATUS in bash, $LASTEXITCODE in PowerShell |
| Notification module missing |
BurntToast/notify-send not installed |
Fallback to terminal bell or Write-Host |
| Silent failure on background job |
Job detached from monitor process |
Use Wait-Job in PowerShell, wait in bash |
| Double notification |
Parent and child process both fire |
Track PID tree, notify only on root process |
| Desktop notification blocked |
System focus assist or DnD mode |
Fallback to terminal output with colored exit code |
| Command output lost |
Notification intercepts stdout/stderr |
Always tee or capture output before monitoring |
Anti-Patterns
| Mistake |
Fix |
| Notify for every command |
Only if >10s threshold |
| Breaking pipes |
Ensure stdout/stderr passthrough |
| Breaking exit codes |
Pass through original exit code |
| Notifications for interactive commands |
Skip if TUI detected |
| Notify and then continue working |
Wait for notification confirmation or user acknowledgment |
| Assuming notification system is available |
Always have a text-only fallback (Write-Host) |
| Monitoring subprocess instead of pipeline |
Track the entire pipeline PID group |
Customization
| Setting |
Default |
Description |
| Threshold |
10s |
Minimum command duration to trigger notification |
| Notification style |
Toast |
toast, bell, or both |
| Include exit code |
Yes |
Show pass/fail in notification |
| Show elapsed time |
Yes |
Include duration in notification text |
| Fallback on failure |
Bell |
What to do if toast notification fails |
Checklist
Sources
- Windows Toast API (docs.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications)
- BurntToast PowerShell module (github.com/Windos/BurntToast)
- notify-send (Linux Desktop Notifications Specification)
- terminal-notifier (github.com/julienXX/terminal-notifier)
- macOS osascript display notification (developer.apple.com)
- POSIX terminal bell (ASCII 0x07)
- Shell job control (bash manual, PowerShell about_Jobs)
1---2name: whendone-plus3description: Automatically notify the user when long-running terminal commands finish (npm test, docker build, git push, etc.). The agent monitors command execution and sends a desktop notification on completion if the command ran longer than threshold (default 10s). Use when user asks to "notify me when done", "desktop notification when command finishes", "alert when done", or "tell me when this completes". Do NOT use for interactive commands (vim, nano, less, htop), commands that always complete in <5s, or streaming commands (tail -f).4license: MIT5---678# WhenDone Plus910Automatically notify when long-running commands complete.1112## How It Works13141. User runs a long command (e.g. `npm test`, `docker build`, `git push`)152. The agent monitors the command execution time163. If the command runs longer than the threshold (default 10s), the agent notifies the user on completion174. Exit code is passed through1819## Workflow2021### Step 1: Detect long-running command2223Identify commands likely to exceed threshold:24- `npm test`, `npm run test`, `npx playwright test`25- `docker build`, `docker compose up`, `docker compose down`26- `git push`, `git pull`, `git clone`27- `pip install`, `npm install`, `pnpm install`, `yarn install`28- `cargo build`, `cargo test`, `go build`, `dotnet build`29- Custom scripts, database migrations, data processing pipelines30- `ffmpeg`, `rsync`, `scp`, large file transfers3132### Step 2: Monitor execution3334Start a background timer when the command begins. Track:35- Elapsed wall-clock time36- Peak memory usage (if available)37- Child process tree (for pipeline awareness)3839### Step 3: Notify on completion4041Basic notification format:42```43✅ "Command finished: npm test completed in 142s (exit 0)"44❌ "Command finished: docker build failed in 89s (exit 1)"45```4647Include:48- Command name (first word + key args)49- Execution time (rounded to seconds)50- Exit code (success/failure)51- Optional: memory peak, output file path if redirected5253### Step 4: Handle edge cases5455- Commands completing under 10s: no notification (too fast to matter)56- Interactive/TUI commands (vim, nano, htop): skip (user is watching)57- Piped commands (e.g. `npm test | grep error`): monitor the pipeline, not the first process58- Backgrounded commands (`&`): notify on background process completion59- Chained commands (`;`): notify per-segment or in aggregate60- Commands killed by signal: notify with signal name (e.g. "killed by SIGTERM")6162## Notification Mechanisms6364### Windows Toast Notification (PowerShell)6566```powershell67Add-Type -AssemblyName System.Windows.Forms68$balloon = New-Object System.Windows.Forms.NotifyIcon69$balloon.Icon = [System.Drawing.SystemIcons]::Information70$balloon.BalloonTipTitle = "Command Complete"71$balloon.BalloonTipText = "npm test finished in 142s (exit 0)"72$balloon.Visible = $true73$balloon.ShowBalloonTip(5000)74Start-Sleep -Seconds 575$balloon.Dispose()76```7778### Terminal Bell (cross-platform)7980```bash81echo -e "\a" # ASCII bell character82printf '\a' # POSIX83```8485### BurntToast Module (Windows 10/11)8687```powershell88Import-Module BurntToast89New-BurntToastNotification -Text "Command Complete", "npm test finished in 142s (exit 0)"90```9192### macOS Notification9394```bash95osascript -e 'display notification "npm test finished in 142s" with title "Command Complete"'96terminal-notifier -title "Command Complete" -message "npm test finished in 142s"97```9899### Linux Notification (notify-send)100101```bash102notify-send "Command Complete" "npm test finished in 142s"103```104105## Error Handling106107| Error | Cause | Fix |108|-------|-------|-----|109| Notification never fires | Command completed under threshold | Expected. Threshold is 10s by default. |110| Wrong exit code reported | Shell pipeline masking failures | Use `$PIPESTATUS` in bash, `$LASTEXITCODE` in PowerShell |111| Notification module missing | BurntToast/notify-send not installed | Fallback to terminal bell or `Write-Host` |112| Silent failure on background job | Job detached from monitor process | Use `Wait-Job` in PowerShell, `wait` in bash |113| Double notification | Parent and child process both fire | Track PID tree, notify only on root process |114| Desktop notification blocked | System focus assist or DnD mode | Fallback to terminal output with colored exit code |115| Command output lost | Notification intercepts stdout/stderr | Always tee or capture output before monitoring |116117## Anti-Patterns118119| Mistake | Fix |120|---------|-----|121| Notify for every command | Only if >10s threshold |122| Breaking pipes | Ensure stdout/stderr passthrough |123| Breaking exit codes | Pass through original exit code |124| Notifications for interactive commands | Skip if TUI detected |125| Notify and then continue working | Wait for notification confirmation or user acknowledgment |126| Assuming notification system is available | Always have a text-only fallback (Write-Host) |127| Monitoring subprocess instead of pipeline | Track the entire pipeline PID group |128129## Customization130131| Setting | Default | Description |132|---------|---------|-------------|133| Threshold | 10s | Minimum command duration to trigger notification |134| Notification style | Toast | toast, bell, or both |135| Include exit code | Yes | Show pass/fail in notification |136| Show elapsed time | Yes | Include duration in notification text |137| Fallback on failure | Bell | What to do if toast notification fails |138139## Checklist140141- [ ] Notification method matches platform (BurntToast on Windows, terminal-notifier on macOS, notify-send on Linux)142- [ ] Threshold duration set appropriately (default 10s — not too short, not too long)143- [ ] Not used for interactive commands (vim, nano, htop, less)144- [ ] Custom message includes the command name and result (success/fail)145- [ ] Fallback: terminal bell or Write-Host if notification fails146147## Sources148149- Windows Toast API (docs.microsoft.com/en-us/windows/apps/design/shell/tiles-and-notifications)150- BurntToast PowerShell module (github.com/Windos/BurntToast)151- notify-send (Linux Desktop Notifications Specification)152- terminal-notifier (github.com/julienXX/terminal-notifier)153- macOS osascript display notification (developer.apple.com)154- POSIX terminal bell (ASCII 0x07)155- Shell job control (bash manual, PowerShell about_Jobs)
eliasoulkadi