TRIGGER SCENARIOS — When to Use CLAM

Rule: ANY mention of a Mac app → try CLAM first. Never say "there's no MCP for this app".

Anti-patterns (never do):

• ❌ Say "QQ音乐没有 MCP 支持" — call clam_find_app("QQ音乐") first
• ❌ Write AppleScript directly — use clam_execute instead
• ❌ Call clam_scan() for discovery — use clam_find_app() (instant, <10ms)

Standard workflow:

clam_find_app(app_name)   # Always start here — instant, no file I/O
    ↓ if not installed
clam_install(app_id)      # ~10 seconds, auto-selects best mode
    ↓ to discover commands
clam_info(app_id)         # Lists all available commands and properties
    ↓ to act
clam_execute(app_id, cmd) # Returns JSON, never raw AppleScript

CLAM — Give AI Hands to Control Mac Apps

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 <app>                  # list all commands for an app
clam install <app>                      # install wrapper (if not already)
clam-<app> --json <command> [args]      # execute
clam --json doctor <app>                # 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.

Scenarios — What Users Will Ask You To Do

When the user makes a request involving their Mac apps, follow this pattern:

1. Install the relevant app wrappers (if not already installed)
2. Use clam --json info to discover available commands
3. Execute commands and use the JSON output for reasoning
4. Present results in a clean, human-readable format

Morning Briefing

User says something like: "What's on my plate today?" / "今天有什么？"

Install and read from three apps:

• Calendar: install → read today's events (times, titles, attendees)
• Mail: install → read unread messages (sender, subject, date)
• Reminders: install → read incomplete reminders (title, due date)

Synthesize into a concise daily brief. Group by urgency. Keep it short — this is a glance, not a report. All read-only, zero risk.

Email Triage

User says: "Help me clean up my inbox" / "帮我整理收件箱"

1. Read all unread messages from Mail
2. Categorize: needs reply / FYI only / can archive
3. Show the categorization to the user FIRST — do not take action without confirmation
4. After user confirms: archive safe emails, mark FYI as read
5. Leave important emails untouched in inbox

Critical rule: never delete emails. Archive only. Always ask before acting.

Organize Downloads

User says: "Clean up my Downloads folder" / "帮我整理 Downloads"

1. Use Finder to list all files in ~/Downloads (name, size, date, type)
2. Categorize: documents, images, installers, code, temp files
3. Show the plan to the user FIRST — list what goes where
4. After user confirms: create subfolders, move files
5. Flag old temp files for deletion but do NOT delete without explicit permission

Play Music

User says: "Play some jazz" / "我想听周杰伦的晴天"

1. Install Music wrapper
2. Search the user's music library for matching tracks
3. Play the result
4. Confirm what's now playing (track name, artist, album)

This is the simplest scenario — immediate action, instant audio feedback.

General App Control

For any other request involving a Mac app:

1. Run clam scan to check if the app is controllable
2. Run clam info to see what commands exist
3. Install if needed, then execute

Always use --json for structured output. Always show the user what you're about to do before taking destructive actions (delete, move, send).

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