Send and Receive iMessages/SMS via imsg CLI on macOS with Hermes Agent

The Apple iMessage skill lets a Hermes Agent read and send iMessages and SMS text messages through the macOS Messages.app, using the imsg command-line tool. You would reach for this when your agent needs to check recent conversations, send a text to a known contact, or watch a chat for new messages. It is a bundled skill, so it ships with Hermes Agent by default and requires no separate installation of the skill itself.

What it does

This skill wraps the imsg CLI, which talks directly to the macOS Messages.app database and send APIs. With it, an agent can list recent chats, read message history (with or without attachment metadata), send text messages with optional file attachments, and watch a specific chat for new incoming messages. The agent can force a message to go as iMessage (blue bubble) or SMS (green bubble), or let Messages.app decide automatically.

Before you start

Three things must be in place before the skill works:

• macOS with Messages.app signed in to an Apple ID.
• imsg installed via Homebrew: brew install steipete/tap/imsg.
• Full Disk Access granted to your terminal application (System Settings → Privacy & Security → Full Disk Access). Without this, imsg cannot read the Messages database.
• Automation permission for Messages.app will be prompted the first time you run an imsg command that sends a message. Accept it.

List Chats

To see recent conversations, use the chats subcommand. The --limit flag controls how many chats to return, and --json outputs structured data that an agent can parse.

imsg chats --limit 10 --json

Each chat object includes the chat ID, display name, and the last message. The agent typically uses the chat ID in subsequent commands.

View History

Once you have a chat ID, you can read the message history. The --limit flag works the same way. Add --attachments to include file metadata (paths, filenames) for any attachments in the history.

# By chat ID
imsg history --chat-id 1 --limit 20 --json

# With attachments info
imsg history --chat-id 1 --limit 20 --attachments --json

Send Messages

The send subcommand requires a recipient (--to) and the message text (--text). The recipient can be a phone number or an email address registered with Apple ID. Optionally, attach a file with --file.

# Text only
imsg send --to "+14155551212" --text "Hello!"

# With attachment
imsg send --to "+14155551212" --text "Check this out" --file /path/to/image.jpg

# Force iMessage or SMS
imsg send --to "+14155551212" --text "Hi" --service imessage
imsg send --to "+14155551212" --text "Hi" --service sms

Watch for New Messages

The watch subcommand polls a chat for new messages and prints them as they arrive. Useful for agents that need to react to incoming texts in real time.

imsg watch --chat-id 1 --attachments

Service Options

• --service imessage, Force iMessage (requires recipient has iMessage enabled)
• --service sms, Force SMS (green bubble)
• --service auto, Let Messages.app decide (default)

Rules

These rules are enforced by the skill's prompt and should be respected by any agent using it:

1. Always confirm recipient and message content before sending
2. Never send to unknown numbers without explicit user approval
3. Verify file paths exist before attaching
4. Don't spam, rate-limit yourself

Example Workflow

A typical interaction: the user asks the agent to text someone. The agent first finds the correct chat, then confirms with the user before sending.

User: "Text mom that I'll be late"

# 1. Find mom's chat
imsg chats --limit 20 --json | jq '.[] | select(.displayName | contains("Mom"))'

# 2. Confirm with user: "Found Mom at +1555123456. Send 'I'll be late' via iMessage?"

# 3. Send after confirmation
imsg send --to "+1555123456" --text "I'll be late"

When not to use it

This skill is for Apple's iMessage and SMS only. For Telegram, Discord, Slack, or WhatsApp messages, use the appropriate gateway channel instead. Group chat management (adding or removing members) is not supported. Bulk or mass messaging is prohibited without explicit user confirmation.

Limits and gotchas

• The skill depends on imsg, which is a third-party tool. If imsg breaks or changes, the skill may stop working until updated.
• Full Disk Access is a macOS security feature that can be revoked by system updates. If the skill stops reading history, check that permission first.
• The --service auto option may send as SMS if iMessage is unavailable, which could incur carrier charges. The agent should inform the user if this is a concern.

Related skills

• Apple Mail, for reading and sending email via the macOS Mail app.
• Apple Reminders, for managing reminders.
• Apple Notes, for reading and creating notes.