Messages

Orchard gives your AI client read/write access to Apple Messages, including scheduled sending, so catching up on texts and sending replies doesn’t mean reaching for your phone. Messages is a Pro feature.

What you can do

“Find my conversation with Jamie and show the last few messages.”
“Did anyone message me about the project deadline today?”
“Send a text to +1 555 123 4567 saying I’m running 10 minutes late.”
“Schedule a message to Mom for 8am tomorrow wishing her a happy birthday.”
“List any messages I have scheduled to go out.”

Available tools

Tool	Description
`messages_read`	Search chats/conversations, or search recent messages, via a `type` parameter.
`messages_send`	Send a message now, or schedule it for a future `scheduled_time`.
`messages_scheduled_list`	List scheduled messages, optionally filtered by status.
`messages_scheduled_cancel`	Cancel a pending scheduled message, or delete sent/cancelled ones.

messages_read takes type=chats to find conversations (by contact name, phone number, or group name) or type=messages to search message text, optionally scoped to a chat_identifier. messages_send accepts either a chat_identifier (phone number or email) or a contact_name to look up, plus a service_name of iMessage or SMS (default iMessage); group chats need a group_name.

Look up chats first

If you don’t know a contact’s exact phone number or chat identifier, call messages_read with type=chats first — it returns the identifiers you need for messages_send or a scoped messages_read with type=messages.

SMS needs iPhone forwarding

Sending over SMS (as opposed to iMessage) only works if your iPhone has Text Message Forwarding enabled for this Mac (Settings > Messages > Text Message Forwarding on iPhone). Without it, SMS sends fail even though the tool accepts the request.

Required permissions

Messages needs two permissions, split by operation:

Full Disk Access — required to read your Messages history (messages_read).
Automation (control of the Messages app) — required to send messages (messages_send).

messages_send needs Full Disk Access too when addressing a chat by contact_name instead of a direct chat_identifier, since looking up the right conversation for a name requires the same access as reading your Messages history.

Unlike Mail, a missing Full Disk Access permission surfaces as a cryptic low-level error rather than a message that names the permission directly. If messages_read fails with an unclear “unable to open” style error, check Full Disk Access first. See Troubleshooting for this exact symptom.

Orchard's Full Disk Access guide window with step-by-step instructions

CLI usage

The orchard messages command exposes read, send, and scheduled (with list / cancel subcommands).

orchard messages read --type chats --query "Jamie"

orchard messages read --type messages --chat "+15551234567" --limit 20

orchard messages send --to "+15551234567" --text "Running 10 minutes late"

--to takes a phone number, email, or a chat identifier from messages read. If you’d rather not look a number up first, --contact-name addresses the recipient by name:

orchard messages send --contact-name "Jamie" --text "Running 10 minutes late"

Group chats need two things together: the group’s chat identifier as --to (find it with read --type chats) and the group’s name as --group-name. Leaving either out fails with “Group name is required for group chats” or a missing-recipient error.

orchard messages read --type chats --query "Weekend Trip"
orchard messages send --to "chat260805679483400512" --group-name "Weekend Trip" --text "See you all Saturday"

orchard messages send --to "+15551234567" --text "Happy birthday!" \
  --scheduled-time "2026-07-14T08:00:00-07:00"

orchard messages scheduled list

Every subcommand accepts --json for machine-readable output. Run orchard messages <subcommand> --help for the full flag list, or orchard help messages <subcommand> for the same information. See the CLI Reference.

Always pass --query with --type chats

--query is listed as optional in --help, but in practice you should always pass it when running orchard messages read --type chats. Omitting it searches with an empty term across every chat, which tends to return noisy or unhelpful results: narrow it to a contact name, number, or group name instead.

Tips & limitations

Orchard needs to stay running for a scheduled send to go out. If it’s quit or restarted before the scheduled time, nothing is lost: the send still happens once Orchard is open again, though it may go out a little late rather than exactly on time. Check pending sends with messages scheduled list.
messages_read with type=messages returns the most recent matches first; use --limit to control how many come back.