imessage

name	imessage
description	Use when an agent needs to inspect or send local macOS iMessage through Atris CLI. Triggers on iMessage, Messages.app, local text messages, chat.db, or texting someone from the user's Mac.
version	1.0.0
tags	["imessage","local","messaging"]

iMessage

Local iMessage is a Mac capability, not a cloud OAuth integration.

Use Atris CLI as the control surface.

1. Check availability first.

atris imessage doctor --json

2. If the doctor says permissions are missing, ask the user to grant Full Disk Access to the terminal or Atris Desktop.

3. Read context only when needed.

atris imessage recent "[phone]" --limit 20

4. Resolve named contacts through the cached local lookup command. Use --refresh only when the cache is stale or the result looks wrong.

atris imessage lookup --name "Exact Contact Name" --json
atris imessage lookup --name "myself" --json

If lookup returns unique: true, use primary.handle for the send. If lookup returns ambiguous: true, ask one concise clarification with the candidate names. If it returns no matches, ask for a phone number or exact contact name. Do not scan Contacts manually or loop over AppleScript; the CLI caches lookup results in ~/.atris/cache/imessage-contacts.json.

5. Never send a message unless the user approved the exact recipient and exact text.

6. For sending, use the fast local send command only after explicit approval.

atris imessage send --to "[phone]" --text "Exact approved text" --approved --json --receipt

The command normalizes US 10-digit phone numbers to +1..., checks doctor, sends through the local Messages AppleScript path using service type = iMessage, and returns JSON proof after the latest-outgoing Messages DB row settles. Use --receipt inside an Atris workspace when the action needs a durable atris/runs/imessage-send-*.md receipt.

If the recipient name is ambiguous, ask one concise clarification before sending. If the user gave a phone number or exact resolved handle, do not search the repo first.

Status Meaning

• connected: true means this Mac can access the local Messages database and local scripting tools.
• connected: false means the user needs macOS permissions, Messages setup, or local tooling.

Boundaries

• Do not route iMessage setup through Google OAuth.
• Do not treat iMessage as a cloud credential.
• Do not upload message contents unless the user explicitly asks.