{
  "schemaVersion": "1.0",
  "item": {
    "slug": "desktop-guardian",
    "name": "Desktop Guardian",
    "source": "tencent",
    "type": "skill",
    "category": "开发工具",
    "sourceUrl": "https://clawhub.ai/s3rous/desktop-guardian",
    "canonicalUrl": "https://clawhub.ai/s3rous/desktop-guardian",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadMode": "redirect",
    "downloadUrl": "/downloads/desktop-guardian",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=desktop-guardian",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "installMethod": "Manual import",
    "extraction": "Extract archive",
    "prerequisites": [
      "OpenClaw"
    ],
    "packageFormat": "ZIP package",
    "includedAssets": [
      "SKILL.md",
      "assets/config.example.yaml",
      "references/hammerspoon-setup.md",
      "references/macos-permissions.md",
      "references/policies.md",
      "scripts/desktop-query.swift"
    ],
    "primaryDoc": "SKILL.md",
    "quickSetup": [
      "Download the package from Yavira.",
      "Extract the archive and review SKILL.md first.",
      "Import or place the package into your OpenClaw setup."
    ],
    "agentAssist": {
      "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
      "steps": [
        "Download the package from Yavira.",
        "Extract it into a folder your agent can access.",
        "Paste one of the prompts below and point your agent at the extracted folder."
      ],
      "prompts": [
        {
          "label": "New install",
          "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
        },
        {
          "label": "Upgrade existing",
          "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
        }
      ]
    },
    "sourceHealth": {
      "source": "tencent",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-04-30T16:55:25.780Z",
      "expiresAt": "2026-05-07T16:55:25.780Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network",
        "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"",
        "redirectLocation": null,
        "bodySnippet": null
      },
      "scope": "source",
      "summary": "Source download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this source.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/desktop-guardian"
    },
    "validation": {
      "installChecklist": [
        "Use the Yavira download entry.",
        "Review SKILL.md after the package is downloaded.",
        "Confirm the extracted package contains the expected setup assets."
      ],
      "postInstallChecks": [
        "Confirm the extracted package includes the expected docs or setup files.",
        "Validate the skill or prompts are available in your target agent workspace.",
        "Capture any manual follow-up steps the agent could not complete."
      ]
    },
    "downloadPageUrl": "https://openagent3.xyz/downloads/desktop-guardian",
    "agentPageUrl": "https://openagent3.xyz/skills/desktop-guardian/agent",
    "manifestUrl": "https://openagent3.xyz/skills/desktop-guardian/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/desktop-guardian/agent.md"
  },
  "agentAssist": {
    "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.",
    "steps": [
      "Download the package from Yavira.",
      "Extract it into a folder your agent can access.",
      "Paste one of the prompts below and point your agent at the extracted folder."
    ],
    "prompts": [
      {
        "label": "New install",
        "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete."
      },
      {
        "label": "Upgrade existing",
        "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run."
      }
    ]
  },
  "documentation": {
    "source": "clawhub",
    "primaryDoc": "SKILL.md",
    "sections": [
      {
        "title": "Desktop Guardian",
        "body": "Full macOS GUI access and desktop automation for OpenClaw, powered by Hammerspoon."
      },
      {
        "title": "🖥️ GUI Access",
        "body": "Query all open windows, apps, and dialogs with full detail (titles, buttons, states)\nClose specific windows or tabs — not just kill entire apps\nClick buttons in system dialogs and popups (with safety guardrails)\nSend keypresses to any app\nQuit or force-quit apps programmatically\nChrome DevTools Protocol integration for tab-level browser control"
      },
      {
        "title": "🛡️ Active Desktop Monitoring",
        "body": "Watches for system dialogs, permission prompts, error popups, and alerts in real-time\nAuto-dismisses known-safe dialogs (e.g., \"app downloaded from internet\")\nAlerts you via Telegram/chat when human input is needed (e.g., security prompts)\nDetects and closes unauthorized apps and excess browser windows/tabs\nEnforces configurable desktop policies via YAML rules\nLogs every action for full audit trail"
      },
      {
        "title": "Requirements",
        "body": "macOS (Tahoe or later)\nHammerspoon (installed automatically) + Accessibility permission\nPython 3 + PyYAML (installed automatically)\nOptional: Chrome with --remote-debugging-port=9222 for tab-level control"
      },
      {
        "title": "Installation",
        "body": "bash scripts/install.sh\n\nThis will:\n\nInstall Hammerspoon if needed\nInstall the DesktopGuardian Spoon\nGuide you through Accessibility permission\nCompile the Swift fallback for degraded mode\nSet up config, logs, and LaunchAgent"
      },
      {
        "title": "Configuration",
        "body": "Config file: ~/.openclaw/skills/desktop-guardian/policy.yaml\n\nSee assets/config.example.yaml for all options. Key settings:\n\ncleanup.enabled: Master switch for auto-cleanup (default: true)\ncleanup.apps.whitelist: Apps allowed to run; others get closed\nbrowsers.chrome.max_windows/max_tabs: Limits before auto-close\ndialogs.auto_dismiss: Apps whose dialogs are safe to dismiss\ndialogs.ignore: Apps whose dialogs should be silently ignored\nalerts.notify_on_actions: Send notification for every auto-action"
      },
      {
        "title": "Chrome Tab Monitoring",
        "body": "For tab-level granularity, Chrome must run with CDP enabled:\n\nopen -a \"Google Chrome\" --args --remote-debugging-port=9222\n\nWithout CDP, only window counts are available."
      },
      {
        "title": "Kill Switch",
        "body": "Instantly disable all actions:\n\ntouch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH\n\nRemove to re-enable:\n\nrm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH"
      },
      {
        "title": "Graceful Degradation",
        "body": "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."
      },
      {
        "title": "helpers.py Subcommands",
        "body": "parse_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"
      },
      {
        "title": "Security",
        "body": "Never interpolates shell variables into hs -c commands\nHardcoded button blacklist: won't click Allow, Delete, Install, etc.\nHardcoded app blacklist: won't dismiss SecurityAgent, Keychain Access, etc.\nAll app names validated against ^[a-zA-Z0-9 ._-]+$\nConfig file mode 600, state uses atomic writes\nFull audit log of every action taken"
      },
      {
        "title": "Uninstall",
        "body": "bash scripts/uninstall.sh\n\nRemoves LaunchAgent, Spoon, and init.lua entries. Preserves config/logs unless you choose to remove them. Does NOT uninstall Hammerspoon."
      }
    ],
    "body": "Desktop Guardian\n\nFull macOS GUI access and desktop automation for OpenClaw, powered by Hammerspoon.\n\nWhat It Does\n🖥️ GUI Access\nQuery all open windows, apps, and dialogs with full detail (titles, buttons, states)\nClose specific windows or tabs — not just kill entire apps\nClick buttons in system dialogs and popups (with safety guardrails)\nSend keypresses to any app\nQuit or force-quit apps programmatically\nChrome DevTools Protocol integration for tab-level browser control\n🛡️ Active Desktop Monitoring\nWatches for system dialogs, permission prompts, error popups, and alerts in real-time\nAuto-dismisses known-safe dialogs (e.g., \"app downloaded from internet\")\nAlerts you via Telegram/chat when human input is needed (e.g., security prompts)\nDetects and closes unauthorized apps and excess browser windows/tabs\nEnforces configurable desktop policies via YAML rules\nLogs every action for full audit trail\nRequirements\nmacOS (Tahoe or later)\nHammerspoon (installed automatically) + Accessibility permission\nPython 3 + PyYAML (installed automatically)\nOptional: Chrome with --remote-debugging-port=9222 for tab-level control\nInstallation\nbash scripts/install.sh\n\n\nThis will:\n\nInstall Hammerspoon if needed\nInstall the DesktopGuardian Spoon\nGuide you through Accessibility permission\nCompile the Swift fallback for degraded mode\nSet up config, logs, and LaunchAgent\nConfiguration\n\nConfig file: ~/.openclaw/skills/desktop-guardian/policy.yaml\n\nSee assets/config.example.yaml for all options. Key settings:\n\ncleanup.enabled: Master switch for auto-cleanup (default: true)\ncleanup.apps.whitelist: Apps allowed to run; others get closed\nbrowsers.chrome.max_windows/max_tabs: Limits before auto-close\ndialogs.auto_dismiss: Apps whose dialogs are safe to dismiss\ndialogs.ignore: Apps whose dialogs should be silently ignored\nalerts.notify_on_actions: Send notification for every auto-action\nChrome Tab Monitoring\n\nFor tab-level granularity, Chrome must run with CDP enabled:\n\nopen -a \"Google Chrome\" --args --remote-debugging-port=9222\n\n\nWithout CDP, only window counts are available.\n\nKill Switch\n\nInstantly disable all actions:\n\ntouch ~/.openclaw/skills/desktop-guardian/KILL_SWITCH\n\n\nRemove to re-enable:\n\nrm ~/.openclaw/skills/desktop-guardian/KILL_SWITCH\n\nGraceful 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\nhelpers.py Subcommands\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\nSecurity\nNever interpolates shell variables into hs -c commands\nHardcoded button blacklist: won't click Allow, Delete, Install, etc.\nHardcoded app blacklist: won't dismiss SecurityAgent, Keychain Access, etc.\nAll app names validated against ^[a-zA-Z0-9 ._-]+$\nConfig file mode 600, state uses atomic writes\nFull audit log of every action taken\nUninstall\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."
  },
  "trust": {
    "sourceLabel": "tencent",
    "provenanceUrl": "https://clawhub.ai/s3rous/desktop-guardian",
    "publisherUrl": "https://clawhub.ai/s3rous/desktop-guardian",
    "owner": "s3rous",
    "version": "2.0.0",
    "license": null,
    "verificationStatus": "Indexed source record"
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/desktop-guardian",
    "downloadUrl": "https://openagent3.xyz/downloads/desktop-guardian",
    "agentUrl": "https://openagent3.xyz/skills/desktop-guardian/agent",
    "manifestUrl": "https://openagent3.xyz/skills/desktop-guardian/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/desktop-guardian/agent.md"
  }
}