| name | imessage |
| description | Send and receive iMessages/SMS via the imsg CLI on macOS. |
| platforms | ["macos"] |
| origin | {"source":"hermes-agent","url":"https://github.com/nousresearch/hermes-agent","version":"9f22977f"} |
| requires | {"bins":["imsg"],"install":[{"kind":"brew","formula":"steipete/tap/imsg","bins":["imsg"],"label":"Install imsg (iMessage CLI)"}]} |
iMessage
Use imsg to read and send iMessage/SMS via macOS Messages.app.
Prerequisites
- macOS with Messages.app signed in
- Install:
brew install steipete/tap/imsg
- Grant Full Disk Access for terminal (System Settings → Privacy → Full Disk Access)
- Grant Automation permission for Messages.app when prompted
When to Use
- User asks to send an iMessage or text message
- Reading iMessage conversation history
- Checking recent Messages.app chats
- Sending to phone numbers or Apple IDs
When NOT to Use
- Telegram/Discord/Slack/WhatsApp messages → use the appropriate gateway channel
- Group chat management (adding/removing members) → not supported
- Bulk/mass messaging → always confirm with user first
Quick Reference
List Chats
imsg chats --limit 10 --json
View History
imsg history --chat-id 1 --limit 20 --json
imsg history --chat-id 1 --limit 20 --attachments --json
Send Messages
imsg send --to "+14155551212" --text "Hello!"
imsg send --to "+14155551212" --text "Check this out" --file /path/to/image.jpg
imsg send --to "+14155551212" --text "Hi" --service imessage
imsg send --to "+14155551212" --text "Hi" --service sms
Watch for New Messages
imsg watch --chat-id 1 --attachments
Service Options
--service imessage — Force iMessage (requires recipient has iMessage)
--service sms — Force SMS (green bubble)
--service auto — Let Messages.app decide (default)
Rules
- Always confirm recipient and message content before sending
- Never send to unknown numbers without explicit user approval
- Verify file paths exist before attaching
- Don't spam — rate-limit yourself
Example Workflow
User: "Text mom that I'll be late"
imsg chats --limit 20 --json | jq '.[] | select(.displayName | contains("Mom"))'
imsg send --to "+1555123456" --text "I'll be late"