{"skill":{"slug":"desktop-guardian","displayName":"Desktop Guardian","summary":"macOS GUI automation and desktop control for OpenClaw, powered by Hammerspoon. Gives your agent full access to interact with the Mac desktop — query windows,...","description":"---\nname: desktop-guardian\ndescription: \"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.\"\n---\n\n# Desktop Guardian\n\nFull macOS GUI access and desktop automation for OpenClaw, powered by **Hammerspoon**.\n\n## What It Does\n\n### 🖥️ GUI Access\n- **Query** all open windows, apps, and dialogs with full detail (titles, buttons, states)\n- **Close** specific windows or tabs — not just kill entire apps\n- **Click buttons** in system dialogs and popups (with safety guardrails)\n- **Send keypresses** to any app\n- **Quit or force-quit** apps programmatically\n- **Chrome DevTools Protocol** integration for tab-level browser control\n\n### 🛡️ Active Desktop Monitoring\n- **Watches** for system dialogs, permission prompts, error popups, and alerts in real-time\n- **Auto-dismisses** known-safe dialogs (e.g., \"app downloaded from internet\")\n- **Alerts you** via Telegram/chat when human input is needed (e.g., security prompts)\n- **Detects and closes** unauthorized apps and excess browser windows/tabs\n- **Enforces** configurable desktop policies via YAML rules\n- **Logs** every action for full audit trail\n\n## Requirements\n\n- macOS (Tahoe or later)\n- Hammerspoon (installed automatically) + Accessibility permission\n- Python 3 + PyYAML (installed automatically)\n- Optional: Chrome with `--remote-debugging-port=9222` for tab-level control\n\n## Installation\n\n```bash\nbash scripts/install.sh\n```\n\nThis will:\n1. Install Hammerspoon if needed\n2. Install the DesktopGuardian Spoon\n3. Guide you through Accessibility permission\n4. Compile the Swift fallback for degraded mode\n5. Set up config, logs, and LaunchAgent\n\n## Configuration\n\nConfig file: `~/.openclaw/skills/desktop-guardian/policy.yaml`\n\nSee `assets/config.example.yaml` for all options. Key settings:\n\n- **cleanup.enabled**: Master switch for auto-cleanup (default: true)\n- **cleanup.apps.whitelist**: Apps allowed to run; others get closed\n- **browsers.chrome.max_windows/max_tabs**: Limits before auto-close\n- **dialogs.auto_dismiss**: Apps whose dialogs are safe to dismiss\n- **dialogs.ignore**: Apps whose dialogs should be silently ignored\n- **alerts.notify_on_actions**: Send notification for every auto-action\n\n## Chrome Tab Monitoring\n\nFor tab-level granularity, Chrome must run with CDP enabled:\n\n```bash\nopen -a \"Google Chrome\" --args --remote-debugging-port=9222\n```\n\nWithout CDP, only window counts are available.\n\n## Kill Switch\n\nInstantly disable all actions:\n```bash\ntouch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH\n```\n\nRemove to re-enable:\n```bash\nrm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH\n```\n\n## Graceful Degradation\n\nWithout Hammerspoon, the skill runs in **monitor-only mode** using a Swift fallback binary. It can detect violations but cannot auto-close or dismiss anything.\n\n## helpers.py Subcommands\n\n```\nparse_config          — Output config as key=value pairs\nvalidate_config       — Validate config (exit 0/1)\ncheck_quiet           — Exit 0 if NOT in quiet hours\nevaluate_snapshot     — Apply policy to snapshot JSON → violations + actions\nparse_query           — Convert snapshot to key=value pairs\nsafe_hs_command       — Generate safe hs -c command string\nupdate_state          — Update alert cooldown state\nlog_violation         — Append to violation log\ndaily_summary         — Generate daily summary\nlist_apps             — List apps from last snapshot\ncheck_cooldown        — Check if alert cooldown has expired\n```\n\n## Security\n\n- **Never** interpolates shell variables into `hs -c` commands\n- Hardcoded button blacklist: won't click Allow, Delete, Install, etc.\n- Hardcoded app blacklist: won't dismiss SecurityAgent, Keychain Access, etc.\n- All app names validated against `^[a-zA-Z0-9 ._-]+$`\n- Config file mode 600, state uses atomic writes\n- Full audit log of every action taken\n\n## Uninstall\n\n```bash\nbash scripts/uninstall.sh\n```\n\nRemoves LaunchAgent, Spoon, and init.lua entries. Preserves config/logs unless you choose to remove them. Does NOT uninstall Hammerspoon.\n","topics":["Browser","Permission"],"tags":{"latest":"2.0.0"},"stats":{"comments":0,"downloads":1224,"installsAllTime":46,"installsCurrent":1,"stars":0,"versions":1},"createdAt":1771789120587,"updatedAt":1779077244184},"latestVersion":{"version":"2.0.0","createdAt":1771789120587,"changelog":"Initial release","license":null},"metadata":null,"owner":{"handle":"s3rous","userId":"s174btvjsk9q547ysgwb4a59xx8857xj","displayName":"s3rous","image":"https://avatars.githubusercontent.com/u/259219366?v=4"},"moderation":{"isSuspicious":false,"isMalwareBlocked":false,"verdict":"clean","reasonCodes":["review.llm_review"],"summary":"Review: review.llm_review","engineVersion":"v2.4.24","updatedAt":1779950282319}}