---
name: clacky
description: Use Clacky's tools on the user's Mac. Alert the user when a long task ends or you need them, keep the Mac awake during long runs, check UI with a screenshot or read on-screen text (grab_text), record a screen demo. Use when the clacky MCP server or the clacky-mcp command is available.
---

# Clacky on the user's Mac

Clacky is a Mac menu-bar app. With **Settings → Connect AI tools** on, it gives
agents a few local tools. The user can switch each group off. A tool that's off,
or Clacky not running, comes back as an error that says so. Tell the user
and carry on without it.

## When to use what

| Situation | Tool |
|---|---|
| A task that ran for more than a minute or two is done, failed, or you need input | `notify` with `title`, optional `message`, `sound` = `done` / `needs` / `error` |
| Starting a long build, test run or download | `keep_awake` `{"on": true, "minutes": 60}`, then `{"on": false}` when finished |
| Check how a UI looks after a change | `take_screenshot` (`screen`, `area` or `window`): returns a file path and a small preview |
| Read text off the screen or from an image or PDF (an error dialog, a receipt, a mockup) | `grab_text` `{"source": "area"}` (the user drags over it) or `{"source": "file", "path": "/abs/or/~/path.png"}`. Returns plain text only |
| Record a short demo of what you built | `start_recording` (optional `seconds`), then `stop_recording` returns the video path |
| Quick context | `get_mac_health` (CPU, memory, disk, battery), `get_mode` / `set_mode` |
| Leave the user a reminder | `add_task` (today or tomorrow), `add_note` |

Keep it light: one `notify` at the end of a long task, not after every step.
Don't take screenshots in a loop. Use them only when seeing the screen answers a question.

## How to call

**MCP** (Claude Code, Claude Desktop, Cursor, Codex): the server is named
`clacky`. Install with:

    claude mcp add --scope user clacky -- /Applications/Clacky.app/Contents/MacOS/clacky-mcp

**Command line** (any agent with a shell, or scripts):

    /Applications/Clacky.app/Contents/MacOS/clacky-mcp list
    /Applications/Clacky.app/Contents/MacOS/clacky-mcp call notify '{"title":"Tests passed"}'
    /Applications/Clacky.app/Contents/MacOS/clacky-mcp call grab_text '{"source":"file","path":"~/Desktop/shot.png"}'

The CLI prints the text result. It exits with 1 when Clacky or the user said no
(the reason is on stderr) and 2 on bad usage.

## Privacy

- Everything stays on the Mac. Clacky uploads nothing. Screenshots and recordings
  are saved locally and only their path (plus a small screenshot preview) comes back.
- Before a screenshot or a screen `grab_text`, Clacky asks the user, unless
  they chose "Take screenshots without asking". If they decline, don't ask again
  straight away.
- `grab_text` reads on-device with Apple Vision. It saves nothing and never
  touches the clipboard.
- No tool reads keystrokes, typed text or clipboard history, and none can.