playbooks

home / skills / openclaw / skills / imsg

imsg skill

This skill lets you manage iMessage and SMS on macOS from the terminal, listing chats, viewing history, watching activity, and sending messages.

npx playbooks add skill openclaw/skills --skill imsg

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
892 B
---
name: imsg
description: iMessage/SMS CLI for listing chats, history, watch, and sending.
homepage: https://imsg.to
metadata: {"clawdbot":{"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 Messages.app iMessage/SMS on macOS.

Requirements
- Messages.app signed in
- Full Disk Access for your terminal
- Automation permission to control Messages.app (for sending)

Common commands
- List chats: `imsg chats --limit 10 --json`
- History: `imsg history --chat-id 1 --limit 20 --attachments --json`
- Watch: `imsg watch --chat-id 1 --attachments`
- Send: `imsg send --to "+14155551212" --text "hi" --file /path/pic.jpg`

Notes
- `--service imessage|sms|auto` controls delivery.
- Confirm recipient + message before sending.

Overview

This skill provides a command-line interface to read and send Messages.app iMessage and SMS on macOS. It exposes commands to list chats, fetch chat history, watch live updates, and send messages and attachments. It is designed for scripting, backups, and lightweight automation of Messages.app interactions. Setup requires Messages signed in and appropriate macOS permissions.

How this skill works

The tool queries the Messages.app database and uses macOS Automation APIs to control message delivery and observe updates. Listing and history commands can output JSON for easy parsing; watch streams new messages and attachments in real time. Sending uses the Automation permissions to instruct Messages.app, with options to choose service (iMessage or SMS) and attach files.

When to use it

  • Scripted backups of conversations or periodic exports
  • Integrating chat data into tooling or personal archives
  • Automating outgoing notifications or replies from a macOS machine
  • Monitoring a specific conversation in real time for updates
  • Quick CLI-based access to messages when GUI is inconvenient

Best practices

  • Grant Full Disk Access to the terminal before running to ensure database reads succeed
  • Enable Automation permission for Messages to allow sending from the CLI
  • Always verify the recipient and message preview before confirm-sending to avoid accidental deliveries
  • Use --json flags for scripts and pipelines to handle output reliably
  • Limit history queries with --limit to avoid large exports and performance issues

Example use cases

  • List recent chats and pipe JSON into a script that extracts phone numbers for a backup
  • Export the last 100 messages of a chat with attachments for archival or legal needs
  • Run imsg watch on a support chat to trigger a local process when new customer messages arrive
  • Send scheduled alerts from a macOS server via imsg send with text and image attachments
  • Combine imsg history --json with tooling to generate a searchable local archive

FAQ

What permissions are required to use this CLI?

Messages must be signed in. Grant Full Disk Access to your terminal to read the database and approve Automation permission to control Messages.app for sending.

How do I control whether a message is sent as iMessage or SMS?

Use the --service option with imessage, sms, or auto. auto chooses the best available service for the recipient.