Description

Give AI hands to control any Mac app. Auto-discover installed apps, generate CLI wrappers, return structured JSON. Works with Music, Finder, Chrome, Word, Fi...

README (SKILL.md)

CLAM — Give AI Hands to Control Mac Apps

Name: Agent Tool Scout
Author: mileszhang001-boom

You can control any macOS application through CLAM. It auto-discovers scriptable apps on the user's Mac, generates CLI wrappers on the fly, and returns structured JSON — all without API keys or manual configuration.

Setup

If clam is not yet installed, run:

pip install clam-mac

What You Can Do

1. Discover what apps are controllable

clam --json scan

This returns a JSON array of all controllable apps with their command count, property count, and mode (full / ui / basic).

2. Install a CLI wrapper for any app

clam install music         # fuzzy match: "chrome" → "google-chrome"

This auto-generates a typed CLI with dozens to hundreds of commands. Takes ~10 seconds, zero configuration.

3. Execute commands and read structured data

clam-music play
clam-music set-sound-volume 50
clam-music --json get-current-track    # → full JSON with 15+ fields
clam-finder --json open ~/Documents
clam-google-chrome --json get-url      # → current tab URL

Every command returns JSON when called with --json. Use this for reasoning and decision-making.

4. Check command reliability before calling

clam --json doctor music

This tells you which commands are fully supported vs. which have parameter type issues. Only call commands marked as supported: true for reliable results.

Command Pattern

clam --json scan                        # discover apps
clam --json info \x3Capp>                  # list all commands for an app
clam install \x3Capp>                      # install wrapper (if not already)
clam-\x3Capp> --json \x3Ccommand> [args]      # execute
clam --json doctor \x3Capp>                # reliability check

Three Modes

Full mode: Apps with .sdef scripting definitions (Music, Finder, Chrome, Word) → dozens to hundreds of commands
UI Scripting mode: Apps without .sdef but with accessible menus (Figma, Slack, VS Code, Spotify) → menu-click automation
Basic mode: Fallback for all .app bundles (WeChat, DingTalk, WPS) → activate, quit, open file, get version

The install command auto-selects the best mode. You don't need to specify it.

Important Notes

macOS only — requires osascript (built-in on all Macs)
Some commands require Automation permission: System Settings > Privacy & Security > Automation
UI Scripting commands require Accessibility permission: System Settings > Privacy & Security > Accessibility
Commands execute via AppleScript with a 30-second timeout
Always use --json flag for structured output when processing results programmatically

Lobster Pipeline Example

CLAM-generated CLIs are standard shell commands, usable as Lobster pipeline steps:

steps:
  - run: clam-music set-sound-volume 20
  - run: clam-music play
  - run: clam-finder open ~/Projects/current

Usage Guidance

What to consider before installing and using this skill: - Origin and trust: The SKILL.md recommends 'pip install clam-mac' from PyPI. Confirm the package author and PyPI project (and check code/release history). The registry entry's homepage points to a GitHub repo — inspect that repo and confirm it matches the package on PyPI. - Review the code: The published bundle contains a full Python virtualenv (many site-packages) and a module named mcp_server. If you plan to install, review src/clam/mcp_server.py and any networking code to see whether it starts servers, binds ports, or sends data externally. - Minimize scope: Run pip install in an isolated environment (dedicated virtualenv or container/VM) rather than system Python. Avoid running it as root. - Be cautious with macOS permissions: The tool requires macOS Automation and Accessibility grants to control other apps — granting those gives the installed tools significant control over your system. Only grant them after you trust the code. - Check credential access: The bundle contains keyring-related packages. If the package attempts to access the system keychain or other secret stores, confirm why and whether that behavior is necessary. - Prompt-injection artifact: The unicode-control-chars finding suggests obfuscated characters in SKILL.md; view the raw file (e.g., in a hex-capable editor) to ensure there is no hidden malicious content or misleading text. - If you need networked behavior: be explicit about it. If you do not want a persistent server, do not run MCP-server components (or run them in an isolated VM and firewall any listening ports). - If unsure: test in a disposable environment (VM) first and audit the installed package files and any network/listening sockets after installation. Prefer manual review or prefer using known, audited packages instead of blindly installing large third-party bundles.

Capability Analysis

Type: OpenClaw Skill Name: agent-tool-scout Version: 0.1.0 The skill provides a framework to control any macOS application via AppleScript and UI scripting, which requires high-privilege 'Accessibility' and 'Automation' permissions. While the core logic in SKILL.md and the demo scripts (demo.py, demo_recording.py) aligns with the stated purpose, the bundle is highly irregular because it includes thousands of lines of source code for standard third-party libraries (docutils, charset_normalizer, certifi) inside a simulated site-packages directory. This non-standard bundling significantly increases the attack surface and makes it difficult to verify if the included library code has been maliciously modified or backdoored. Additionally, the AppleScript generation in demo.py is vulnerable to injection if the input keyword is not sanitized.

Capability Assessment

ℹ Purpose & Capability

The name/description (generate CLI wrappers, control Mac apps via AppleScript) align with the declared requirements (osascript + pip) and SKILL.md instructions. However, the published bundle contains a huge set of code files (a full virtualenv/site-packages, tests, an MCP server, and many source files). Declaring the skill as instruction-only while shipping a large codebase (including third-party packages) is inconsistent and disproportionate: an instruction-only skill should not need the entire venv embedded. The presence of mcp_server.py and other runtime code is more than expected for a simple wrapper generator.

ℹ Instruction Scope

The SKILL.md instructs the agent to run pip install clam-mac and to use clam commands that scan the system, install CLI wrappers, and execute AppleScript (via osascript). Scanning installed apps and generating wrappers logically requires reading system app metadata and invoking osascript; that is consistent with purpose. The instructions explicitly require Automation/Accessibility permissions (macOS privacy), which is appropriate but sensitive. The instructions do not ask for unrelated files or environment variables and do not explicitly transmit data to external endpoints, but the included codebase (MCP server) implies possible networking behavior beyond what SKILL.md documents.

⚠ Install Mechanism

The SKILL.md recommends 'pip install clam-mac' (a standard, expected distribution method). However, the skill bundle as published includes many code files including an entire virtualenv/site-packages tree and tests. That is inconsistent with the 'no install spec / instruction-only' listing and unusual: bundling a full venv in the skill increases disk footprint and attack surface (multiple third-party packages). There is no external download URL in the skill metadata, but if the agent follows the SKILL.md and pip-installs the package, it will pull code from PyPI (expected). The inconsistency between 'instruction-only' and the presence of full source + venv is a red flag worth manual review.

ℹ Credentials

The skill declares no required environment variables or credentials, which is proportionate to its stated local-automation purpose. Nonetheless, the included codebase contains packages (keyring, requests, and other libs) and a module named mcp_server — these could interact with system keyrings or open network endpoints if executed. While nothing in SKILL.md asks for secrets, the presence of keyring-related code means the installed package, if executed, might access system credential stores (this may be legitimate for certain integrations but should be reviewed).

ℹ Persistence & Privilege

The skill is not 'always: true' and does not declare elevated privileges. Still, the project includes an MCP server component and README instructions describing registering an MCP server (Claude Code / MCP). Running or enabling that server would create a persistent network-exposed capability and increase blast radius. Granting Automation/Accessibility permissions (required for many commands) is also sensitive — SKILL.md correctly warns about those macOS permissions. The combination of potential networking (mcp_server) plus local automation permissions merits caution.

Version History

v0.1.0

Initial release of clam-mac: AI-controlled automation for any Mac app. - Auto-discovers installed, scriptable Mac apps and generates CLI wrappers with zero configuration. - Supports 20+ popular apps out of the box (Music, Finder, Chrome, Word, Figma, and more). - All commands return structured JSON with the --json flag for easy integration and reasoning. - Offers three control modes: Full (AppleScript .sdef), UI automation, and basic app operations. - Includes reliability checker (doctor) to verify command support. - Requires macOS with osascript and pip; promotes simple setup and app-level privacy/automation permissions.

Metadata

Slug agent-tool-scout

Version 0.1.0

License MIT-0

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is Agent Tool Scout?

Give AI hands to control any Mac app. Auto-discover installed apps, generate CLI wrappers, return structured JSON. Works with Music, Finder, Chrome, Word, Fi... It is an AI Agent Skill for Claude Code / OpenClaw, with 1828 downloads so far.

How do I install Agent Tool Scout?

Run "/install agent-tool-scout" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Agent Tool Scout free?

Yes, Agent Tool Scout is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does Agent Tool Scout support?

Agent Tool Scout is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Agent Tool Scout?

It is built and maintained by mileszhang001-boom (@mileszhang001-boom); the current version is v0.1.0.

More Skills

Agent Tool Scout