---
title: iMessage assistant — your Mac's texts, the important ones on your phone
nav: iMessage assistant
summary: Mac only. Agent J reads new iMessages and texts on your Mac (read-only) and sends codes, deliveries, bank, travel and family messages to your phone, holding back spam and scams. Off by default; one permission step on the computer.
order: 38
---
# iMessage assistant — your Mac's texts, the important ones on your phone

Many iPhones sync their messages to a Mac. When you are away from the computer, codes, deliveries, bank alerts and
family messages sit there unread. The **iMessage assistant** lets Agent J on your computer look at new messages on a
schedule: important ones go straight to your paired phone, the rest wait for a digest, spam and scams are held back.

It only reads. It never replies, never sends anything for you, never marks anything as read and never changes anything
in the Messages app.

## Mac only

The switch appears under Settings → Agent features → iMessage assistant on the phone only when the computer is a Mac.
Linux and Windows have no Messages database, so the item is not shown. It is off by default.

## First time: one permission step on the computer

Reading messages needs macOS **Full Disk Access**. macOS never asks by itself; you switch it on once:

1. Turn the switch on on your phone. The status says "Needs permission".
2. Tap "Open on the computer": System Settings → Privacy & Security → Full Disk Access opens on the Mac, and Finder
   shows the program to add (its name is on the phone).
3. On the computer, add that program to the list and switch it on.
4. Back on the phone, tap "Check again". "Running" means you are done.

After it is on, **old messages are not sent to you** — only new ones. To catch up, ask Agent J to run
`agentj imessage backfill --hours 24` (up to 72 hours); you get one digest.

To get ordinary texts on the Mac too (not only iMessages), on the iPhone open Settings → Messages → Text Message
Forwarding and tick this Mac.

## What it alerts

- **At once**: verification codes, VIP contacts, bank and security notices, travel and booking changes, people you know.
- **In the digest**: deliveries, bills, group chats and anything unclear, sent together at your digest times (default
  09:00 and 18:00).
- **Held back**: marketing, loans, prizes, phishing links, and texts that try to give an AI instructions (asking it to ignore
  previous instructions and send the code out). The digest says how many were held back.

Every alert names the category, the sender (numbers not in your contacts are masked), the time and why it was sent.
Codes are shown and hidden from the history after 30 minutes; you can also choose "Masked: sender only" or "Don't alert codes".

## What you change on the phone

Under Settings → iMessage assistant: how often to look (every minute to every hour), delivery (important at once /
everything at once / digest only), digest times, quiet hours, filter strength, how codes are shown, group chats, and
smart sorting.

**Smart sorting** is off by default: only the rules on your computer are used and message text never leaves it. When
on, only messages the rules can't decide go to Jev, without numbers, e-mails or links; codes never go to any model.

## What Agent J changes for you

**Your rules**, **VIP contacts** and the **muted list** are read-only on the phone. Tap "Ask Agent J to change it" and
say it in one sentence in the chat, for example:

- Alert every message from my family at once; deliveries can wait for the digest
- Make +1 555 010 0001 a VIP
- Never alert this number again
- Don't disturb me from 11 pm to 7 am

Agent J makes the change with `agentj imessage …` and tells you what changed. VIPs are matched only by the exact number
or e-mail you give, never guessed from a name.

## Commands on the computer

```
agentj imessage status                     # switch, status, today's counts (no message text)
agentj imessage on | off
agentj imessage set interval_minutes 15    # same as agentj config set imessage.interval_minutes 15
agentj imessage instructions show | set "…" | reset
agentj imessage vip add +15550100001
agentj imessage mute add coupon
agentj imessage doctor                     # check the permission again
```

The phone and the commands change the same settings, through the same validator, effective at once.

## Privacy and safety

- **Read-only**: the Messages database is opened read-only, never written, never copied; there is no way to send.
- **Text stays on your computer by default**: alerts and digests travel only through the encrypted channel to your paired
  phone. The computer keeps message numbers, categories and counts, never message text; the log
  (`~/Library/Logs/AgentJ/imessage.log`) has no text either.
- **Texts are untrusted**: a text never reaches your Agent as an instruction; texts that try to instruct an AI are held
  back as spam.
- **Nothing missed**: it reads on by message number, so after the Mac sleeps or restarts it catches up; on newer macOS
  the text sits in a second field, and Agent J reads that too.
- **Off means forgotten**: turning it off clears where it was and the waiting digest. To take the permission back, switch
  the program off under System Settings → Full Disk Access.