# Imessage

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

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

---


# iMessage

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

Use Atris CLI as the control surface.

1. Check availability first.

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

```bash
atris imessage recent "+15555555555" --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.

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

```bash
atris imessage send --to "+15555555555" --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.