# Imessage Smart

> 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.

- Skill: `meleantonio/imessage-smart` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add meleantonio/imessage-smart`
- Raw SKILL.md: https://api.skillmd.com/api/skills/meleantonio/imessage-smart/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: meleantonio (https://skillmd.com/u/meleantonio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/meleantonio/imessage-smart

---


# 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. `+46701234567`) or Apple ID email.

## Scripts (from repo `workstation/` root)

Read recent messages (JSON on stdout):

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

Send a message:

```bash
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.