Skill

Review

Audit score 70

imsg

steipete/clawdis

iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app

What is imsg?

A command-line interface to read and send iMessage/SMS messages through macOS Messages.app. Use this when you need to check conversation history, list chats, or send messages to phone numbers or Apple IDs.

List recent chats with optional JSON output
View message history for a specific chat with attachments info
Watch for new incoming messages in real-time
Send text messages with optional file attachments
Force iMessage, SMS, or auto-select service type
Confirm recipient and message content before sending

How to install imsg

npx skills add https://github.com/steipete/clawdis --skill imsg

Prerequisites

macOS with Messages.app signed in
Full Disk Access permission for terminal
Automation permission for Messages.app
imsg CLI tool installed via brew (steipete/tap/imsg)

Claude Code

Cursor

Windsurf

Cline

How to use imsg

1.Install imsg via Homebrew: brew install steipete/tap/imsg
2.Ensure Messages.app is signed in and has necessary permissions
3.List available chats: imsg chats --limit 10 --json
4.View message history: imsg history --chat-id <id> --limit 20 --json
5.Send a message: imsg send --to <recipient> --text <message>
6.Optionally add attachments: imsg send --to <recipient> --text <message> --file <path>

Use cases

Good for

Send a text message to a phone number or Apple ID when user requests it
Check recent iMessage conversation history
List all active chats to find a specific contact
Monitor a chat for new incoming messages
Send a message with an image or file attachment

Who it's for

macOS users who want CLI access to Messages.app
Developers automating message workflows on Mac
Users managing iMessage/SMS from terminal or agents

imsg FAQ

When should I use imsg vs other messaging tools?

Use imsg only for iMessage/SMS via Messages.app. For Telegram, Signal, WhatsApp, Discord, or Slack, use their respective channels or skills.

Do I need to confirm before sending messages?

Yes, always confirm the recipient and message content with the user before sending. Never send to unknown numbers without explicit approval.

Can I send messages with attachments?

Yes, use the --file flag to attach images or other files. Always confirm the file path exists before sending.

What permissions does imsg need?

Full Disk Access for the terminal and Automation permission for Messages.app to read chats and send messages.

Can imsg manage group chats or add/remove members?

No, imsg only supports reading history and sending messages. Group management is not supported.

Full instructions (SKILL.md)

Source of truth, from steipete/clawdis.

name: imsg description: "iMessage/SMS CLI for listing chats, history, and sending messages via Messages.app." homepage: https://imsg.to metadata: { "openclaw": { "emoji": "📨", "os": ["darwin"], "requires": { "bins": ["imsg"] }, "install": [ { "id": "brew", "kind": "brew", "formula": "steipete/tap/imsg", "bins": ["imsg"], "label": "Install imsg (brew)", }, ], }, }

imsg

Use imsg to read and send iMessage/SMS via macOS Messages.app.

When to Use

Use when:

User explicitly asks to send iMessage or SMS
Reading iMessage conversation history
Checking recent Messages.app chats
Sending to phone numbers or Apple IDs

When NOT to Use

Do not use when:

Telegram messages -> use message tool with channel:telegram
Signal messages -> use Signal channel if configured
WhatsApp messages -> use WhatsApp channel if configured
Discord messages -> use message tool with channel:discord
Slack messages -> use slack skill
Group chat management (adding/removing members) -> not supported
Bulk/mass messaging -> always confirm with user first
Replying in current conversation -> just reply normally (OpenClaw routes automatically)

Requirements

macOS with Messages.app signed in
Full Disk Access for terminal
Automation permission for Messages.app (for sending)

Common Commands

List Chats

imsg chats --limit 10 --json

View History

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

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

Watch for New Messages

imsg watch --chat-id 1 --attachments

Send Messages

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

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

# Specify service
imsg send --to "+14155551212" --text "Hi" --service imessage
imsg send --to "+14155551212" --text "Hi" --service sms

Service Options

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

Safety Rules

Always confirm recipient and message content before sending
Never send to unknown numbers without explicit user approval
Be careful with attachments - confirm file path exists
Rate limit yourself - don't spam

Example Workflow

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"