imessage

Read and send iMessage and SMS messages via macOS Messages.app using the imsg CLI.

6|1|Updated May 11, 2026
One-click install
npx skills add https://github.com/yakeworld/Synthos --skill imessage-yakeworld
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: imessage
Source: https://github.com/yakeworld/Synthos/tree/main/skills/extended/external-automation/apple/imessage
Command: npx skills add https://github.com/yakeworld/Synthos --skill imessage-yakeworld

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Sending or reading iMessage/SMS conversations on macOS normally requires manual interaction with Messages.app. This Skill lets an AI agent list chats, view history, and send messages or attachments through the imsg command-line tool, with built-in confirmation and safety rules. ## Core Features & Use Cases - Chat Discovery & History: List recent chats and read conversation history (with attachment info) as JSON via imsg chats and imsg history. - Message Sending: Send text or file attachments to phone numbers or Apple IDs, with explicit --service imessage|sms channel selection. - Safety Guardrails: Mandatory recipient/content confirmation before sending, blocking of unapproved unknown numbers, and structured error responses with recovery suggestions. - Use Case: A user says "Text mom that I'll be late" — the agent locates Mom's chat via imsg chats, confirms the recipient and message with the user, then sends via imsg send --service imessage. ## Quick Start Ask the agent to find a contact's chat with imsg and send them a short iMessage after confirming the recipient and message content.

Frequently Asked Questions about imessage

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I send an iMessage from the command line on macOS?

Install the imsg CLI with brew install steipete/tap/imsg, then run imsg send --to "+14155551212" --text "Hello!". Messages.app must be signed in, and the terminal needs Full Disk Access and Automation permission for Messages.app.

How to read iMessage history from the terminal?

Use imsg chats --limit 10 --json to list recent conversations, then imsg history --chat-id <id> --limit 20 --json to view messages. Add --attachments to include attachment information in the output.

Can I force SMS instead of iMessage when sending?

Yes, pass --service sms to force SMS (green bubble) or --service imessage to force iMessage. The default --service auto lets Messages.app decide based on the recipient's capabilities.

Does imsg work for WhatsApp, Telegram, or Slack messages?

No, imsg only interacts with macOS Messages.app for iMessage and SMS. For Telegram, Discord, Slack, or WhatsApp, use the appropriate gateway channel for that platform instead.

Why does imsg fail to read chats or send messages?

Common causes are missing Full Disk Access for the terminal, Messages.app not being signed in, or Automation permission not granted. Check System Settings → Privacy → Full Disk Access and approve the Messages.app automation prompt.