Imsg
Let your agent list iMessage/SMS chats, read history, and send messages through macOS Messages.app via the imsg CLI when the user explicitly wants Apple messaging.
Overview
imsg is an agent skill for the Build phase that lists chats, reads iMessage/SMS history, and sends messages via the imsg CLI on macOS Messages.app when the user explicitly requests Apple messaging.
Install
npx skills add https://github.com/steipete/clawdis --skill imsgWhat is this skill?
- Read/send iMessage and SMS through Messages.app using the imsg binary
- Explicit triggers: send iMessage/SMS, read history, recent chats—to phone numbers or Apple IDs
- Homebrew install path: steipete/tap/imsg formula
- macOS-only (darwin); requires Full Disk Access and Automation permission for sending
- When NOT to use matrix: Telegram, Signal, WhatsApp, Discord, Slack—use their dedicated channels/skills
- Requires imsg binary via brew formula steipete/tap/imsg
- Documented When NOT to Use list for 7+ alternate channels
Adoption & trust: 1.9k installs on skills.sh; 378k GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent can chat in the IDE but cannot reach a contact on iMessage or SMS unless you wire a macOS-native CLI with the right permissions.
Who is it for?
macOS users with Messages.app signed in who want agent-driven read/send for iMessage or SMS with clear channel boundaries.
Skip if: Linux/Windows setups, bulk or mass messaging without confirmation, group member management, or Telegram/Slack/WhatsApp (use those channel skills instead).
When should I use this skill?
User explicitly asks to send iMessage or SMS, read iMessage history, or check recent Messages.app chats.
What do I get? / Deliverables
The agent runs documented imsg commands to inspect or send Apple messages after explicit user intent, without misusing other channel tools.
- Sent iMessage/SMS per user request
- Chat listings or history excerpts from Messages.app
Recommended Skills
Journey fit
How it compares
macOS Messages.app CLI integration—not the generic in-conversation reply router and not cross-platform chat APIs.
Common Questions / FAQ
Who is imsg for?
Developers on macOS who run OpenClaw-style agents and need documented, permission-aware access to iMessage and SMS through the imsg binary.
When should I use imsg?
During Build integrations when the user explicitly asks to send iMessage/SMS, read Messages history, or list recent chats—not for ordinary thread replies the host already handles.
Is imsg safe to install?
Check the Security Audits panel on this Prism page; granting Full Disk Access and Messages automation is sensitive—install imsg only from the documented Homebrew tap and confirm each send.
SKILL.md
READMESKILL.md - Imsg
# 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 ```bash imsg chats --limit 10 --json ``` ### View History ```bash # 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 ```bash imsg watch --chat-id 1 --attachments ``` ### Send Messages ```bash # 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 1. **Always confirm recipient and message content** before sending 2. **Never send to unknown numbers** without explicit user approval 3. **Be careful with attachments** - confirm file path exists 4. **Rate limit yourself** - don't spam ## Example Workflow User: "Text mom that I'll be late" ```bash # 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" ```