| name | desktop-guardian |
| description | macOS GUI automation and desktop control for OpenClaw, powered by Hammerspoon. Gives your agent full access to interact with the Mac desktop — query windows, manage apps, close browser tabs, click dialog buttons, dismiss popups, and send keypresses. Includes an always-on desktop guardian that actively monitors for system dialogs, permission prompts, error popups, and unauthorized apps, taking action automatically or alerting you when human input is needed. Use when: (1) your agent needs to interact with the macOS GUI, (2) monitoring and responding to desktop popups/dialogs/alerts, (3) managing open apps, browser windows, and tabs, (4) enforcing desktop cleanliness policies, (5) any macOS Accessibility automation from OpenClaw. |
Desktop Guardian
Full macOS GUI access and desktop automation for OpenClaw, powered by Hammerspoon.
What It Does
🖥️ GUI Access
- Query all open windows, apps, and dialogs with full detail (titles, buttons, states)
- Close specific windows or tabs — not just kill entire apps
- Click buttons in system dialogs and popups (with safety guardrails)
- Send keypresses to any app
- Quit or force-quit apps programmatically
- Chrome DevTools Protocol integration for tab-level browser control
🛡️ Active Desktop Monitoring
- Watches for system dialogs, permission prompts, error popups, and alerts in real-time
- Auto-dismisses known-safe dialogs (e.g., "app downloaded from internet")
- Alerts you via Telegram/chat when human input is needed (e.g., security prompts)
- Detects and closes unauthorized apps and excess browser windows/tabs
- Enforces configurable desktop policies via YAML rules
- Logs every action for full audit trail
Requirements
- macOS (Tahoe or later)
- Hammerspoon (installed automatically) + Accessibility permission
- Python 3 + PyYAML (installed automatically)
- Optional: Chrome with
--remote-debugging-port=9222 for tab-level control
Installation
bash scripts/install.sh
This will:
- Install Hammerspoon if needed
- Install the DesktopGuardian Spoon
- Guide you through Accessibility permission
- Compile the Swift fallback for degraded mode
- Set up config, logs, and LaunchAgent
Configuration
Config file: ~/.openclaw/skills/desktop-guardian/policy.yaml
See assets/config.example.yaml for all options. Key settings:
- cleanup.enabled: Master switch for auto-cleanup (default: true)
- cleanup.apps.whitelist: Apps allowed to run; others get closed
- browsers.chrome.max_windows/max_tabs: Limits before auto-close
- dialogs.auto_dismiss: Apps whose dialogs are safe to dismiss
- dialogs.ignore: Apps whose dialogs should be silently ignored
- alerts.notify_on_actions: Send notification for every auto-action
Chrome Tab Monitoring
For tab-level granularity, Chrome must run with CDP enabled:
open -a "Google Chrome" --args --remote-debugging-port=9222
Without CDP, only window counts are available.
Kill Switch
Instantly disable all actions:
touch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH
Remove to re-enable:
rm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH
Graceful Degradation
Without Hammerspoon, the skill runs in monitor-only mode using a Swift fallback binary. It can detect violations but cannot auto-close or dismiss anything.
helpers.py Subcommands
parse_config — Output config as key=value pairs
validate_config — Validate config (exit 0/1)
check_quiet — Exit 0 if NOT in quiet hours
evaluate_snapshot — Apply policy to snapshot JSON → violations + actions
parse_query — Convert snapshot to key=value pairs
safe_hs_command — Generate safe hs -c command string
update_state — Update alert cooldown state
log_violation — Append to violation log
daily_summary — Generate daily summary
list_apps — List apps from last snapshot
check_cooldown — Check if alert cooldown has expired
Security
- Never interpolates shell variables into
hs -c commands
- Hardcoded button blacklist: won't click Allow, Delete, Install, etc.
- Hardcoded app blacklist: won't dismiss SecurityAgent, Keychain Access, etc.
- All app names validated against
^[a-zA-Z0-9 ._-]+$
- Config file mode 600, state uses atomic writes
- Full audit log of every action taken
Uninstall
bash scripts/uninstall.sh
Removes LaunchAgent, Spoon, and init.lua entries. Preserves config/logs unless you choose to remove them. Does NOT uninstall Hammerspoon.
