WhenDone Plus

Automatically notify when long-running commands complete.

How It Works

1. User runs a long command (e.g. npm test, docker build, git push)
2. The agent monitors the command execution time
3. If the command runs longer than the threshold (default 10s), the agent notifies the user on completion
4. 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 test
• docker build, docker compose up, docker compose down
• git push, git pull, git clone
• pip install, npm install, pnpm install, yarn install
• cargo 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

• Notification method matches platform (BurntToast on Windows, terminal-notifier on macOS, notify-send on Linux)
• Threshold duration set appropriately (default 10s — not too short, not too long)
• Not used for interactive commands (vim, nano, htop, less)
• Custom message includes the command name and result (success/fail)
• Fallback: terminal bell or Write-Host if notification fails

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)