os-automation

name	os-automation
category	system
description	Cross-platform OS automation — send desktop notifications, read and write the clipboard, take screenshots, open files and URLs in default apps, launch and manage applications, control system volume, check WiFi status, create scheduled tasks and cron jobs, and manage display brightness. Use when the user asks to send a notification, copy to clipboard, take a screenshot, open a file or URL, launch an app, adjust volume, check WiFi, schedule a task, or control OS UI and system settings on macOS, Windows, or Linux. Do not use for running arbitrary shell commands or scripts — use the shell tool instead.
license	MIT
compatibility	Uses built-in OS utilities; some features require specific tools (see per-platform references)
metadata	{"author":"zeph","version":"1.1"}

OS Automation

Automate OS-level actions using platform-native utilities.

Before running commands, detect the OS and load the matching reference for platform-specific syntax:

• macOS — references/macos.md (osascript, pbcopy/pbpaste, screencapture, networksetup, open, launchctl)
• Linux — references/linux.md (notify-send, xclip/wl-copy, scrot/grim, xdg-open, amixer/pactl, nmcli)
• Windows — references/windows.md (PowerShell: Set-Clipboard, BurntToast, schtasks, netsh)

OS detection:

uname -s 2>/dev/null || echo Windows

Capability Matrix

Task	macOS	Linux	Windows
Desktop notification	osascript	notify-send	PowerShell / BurntToast
Clipboard read	pbpaste	xclip / wl-paste	Get-Clipboard
Clipboard write	pbcopy	xclip / wl-copy	Set-Clipboard
Screenshot	screencapture	scrot / grim	snippingtool / PowerShell
Open file / URL	open	xdg-open	Start-Process
Launch app	open -a "App"	gtk-launch / app name	Start-Process
Volume control	osascript	amixer / pactl	PowerShell / nircmd
WiFi status	networksetup	nmcli / iwconfig	netsh wlan
Scheduled tasks	crontab / launchctl	crontab / systemd timer	schtasks / Register-ScheduledTask
Display brightness	brightness (brew)	brightnessctl / xrandr	PowerShell / WMI
Text-to-speech	say	espeak / festival	Add-Type / SAPI
System sleep

Workflow

1. Detect OS first — always.
2. Load the matching reference file for exact command syntax.
3. For read-only actions (clipboard read, WiFi status, screenshots to file), proceed directly.
4. For write or side-effect actions (volume change, notification, scheduled task), show what will be done and confirm with the user.
5. After execution, verify the result where possible (check clipboard content, confirm notification sent, verify cron entry exists).

Safety Rules

ALWAYS follow these rules — no exceptions:

1. Preview before acting — for any action that modifies system state (volume, brightness, scheduled tasks, system settings), show the exact command and what it will do before executing.

2. Confirm irreversible actions — never remove cron entries, kill processes, or change system-wide settings (firewall, network, proxy) without explicit user confirmation.

3. Never send keystrokes or click UI elements without an explicit user request for each action.

4. Screen captures may contain sensitive data — treat screenshot output files as sensitive. Do not display screenshot content beyond what is needed.

5. networksetup (macOS) requires sudo for some operations — warn the user before running commands that may require elevated privileges. Never attempt sudo without the user's knowledge.

6. PowerShell ExecutionPolicy — if blocked by ExecutionPolicy on Windows, explain the restriction and suggest Set-ExecutionPolicy RemoteSigned -Scope CurrentUser only if the user wants to proceed.

7. Scheduled tasks — always display the full cron expression or task definition before creating. Explain what it will run, when, and with what permissions.

8. Volume and brightness — show the current level before changing it so the user can gauge the delta.

Common Patterns

Send a desktop notification

# macOS
osascript -e 'display notification "Task complete" with title "Zeph"'

# Linux
notify-send "Zeph" "Task complete"

# Windows (PowerShell)
[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] | Out-Null

Copy text to clipboard

# macOS
echo "text" | pbcopy

# Linux (X11)
echo "text" | xclip -selection clipboard

# Windows
Set-Clipboard -Value "text"

Take a screenshot

# macOS — save to file
screencapture -x ~/Desktop/screenshot.png

# macOS — selection only
screencapture -s ~/Desktop/screenshot.png

# Linux (scrot)
scrot ~/screenshot.png

# Windows (PowerShell)
Add-Type -AssemblyName System.Windows.Forms
[System.Windows.Forms.SendKeys]::SendWait('%{PRTSC}')

Open a file or URL

# macOS
open https://example.com
open ~/Documents/file.pdf

# Linux
xdg-open https://example.com
xdg-open ~/Documents/file.pdf

# Windows
Start-Process https://example.com

Schedule a recurring task (cron)

# Show current crontab first
crontab -l

# Add entry (macOS / Linux)
(crontab -l 2>/dev/null; echo "0 9 * * 1-5 /path/to/script.sh") | crontab -

Notes

• Some tools are optional and may not be installed on all systems (e.g. notify-send requires libnotify, brightnessctl may need installation on Linux).
• On Linux, clipboard tools differ for X11 (xclip, xsel) vs Wayland (wl-copy, wl-paste). Detect with echo $WAYLAND_DISPLAY.
• macOS screencapture -x suppresses the shutter sound.
• Always prefer the platform reference file for exact flags and edge cases.