imessage-smart

name	imessage-smart
description	Reads recent iMessage history from the local Messages database and sends iMessages via AppleScript. Use when the user asks to text someone, check conversation context before replying, or send an iMessage from a self-hosted Cursor agent on macOS.

iMessage (smart)

When to use

• Before composing a reply, read recent messages so responses match thread context.
• When the user names a person or phone/email — match handle_id or chat display name with the read script.
• After the user confirms wording, send with the send script.

Prerequisites

• macOS with Messages / iMessage signed in.
• Full Disk Access for the app running the agent (Terminal, Cursor, or agent worker) so ~/Library/Messages/chat.db is readable.
• Recipient for send: phone in E.164 (e.g. [phone]) or Apple ID email.

Scripts (from repo workstation/ root)

Read recent messages (JSON on stdout):

python3 workstation/.cursor/skills/imessage-smart/scripts/read_recent_messages.py \
  --contact "+4670..." --limit 15

Send a message:

python3 workstation/.cursor/skills/imessage-smart/scripts/send_imessage.py \
  --to "+4670..." --body "Your text here"

Paths: if the skill lives under workstation/.cursor/skills/imessage-smart/, resolve workstation as the directory containing .cursor.

Agent workflow

1. Run read with a distinctive substring of the handle (phone/email) or display name.
2. Summarize thread for the user; propose a reply draft.
3. On approval, run send with the same handle format Messages expects.

Safety

• Do not send unsolicited or sensitive content; confirm with the user when unclear.
• If chat.db errors occur, suggest Full Disk Access and that Messages may need to be quit for heavy read contention.