imsg is a Swift CLI for reading, watching, and sending iMessage and SMS from macOS. It reads the local Messages database, sends through Messages.app automation, and exposes NDJSON and JSON-RPC for scripts and agents.
imsg chats --limit 10 --json | jq -s
imsg history --chat-id 42 --limit 20 --attachments --json | jq -s
imsg watch --chat-id 42 --reactions --json
imsg send --to "+14155551212" --text "on my way"That's the whole pitch: read directly, stream updates, and ask Messages.app to send.
Homebrew is the smallest path on macOS:
brew install steipete/tap/imsg
imsg --versionimsg requires macOS 14 or newer. Signed macOS builds and Linux x86_64 read-only builds are also available from GitHub Releases. Linux reads a chat.db copied from macOS; it does not connect to iMessage or send messages. See the Linux guide.
Grant your terminal Full Disk Access in System Settings → Privacy & Security, then reopen it. imsg needs that permission to read ~/Library/Messages/chat.db.
# Find a chat and note its id.
imsg chats --limit 3
# Read its ten most recent messages.
imsg history --chat-id 42 --limit 10Use an id from the first command in place of 42. The five-minute quickstart continues with live watching and sending.
| Goal | Start here |
|---|---|
| List chats and inspect their identifiers | Chats and groups |
| Read or search local history | History |
| Stream new messages and tapbacks | Watch |
| Send text, files, and standard tapbacks | Send and attachments |
| Count messages and media | Statistics |
| Consume stable NDJSON or a long-running stdio API | JSON schema and JSON-RPC |
| Generate shell completions or model-ready CLI help | Completions |
Read commands open the database in SQLite read-only mode. watch follows database and WAL filesystem events, with a polling fallback when macOS drops an event or rotates a sidecar file.
Full Disk Access is required for local database reads. Sending and standard tapbacks also require Automation → Messages; Contacts access is optional and only adds resolved names. The permissions guide covers parent-process grants and stale TCC entries, while troubleshooting maps common failures to their likely gate.
For SMS, enable Text Message Forwarding on the paired iPhone. imsg send uses Messages.app's AppleScript surface and cannot force a particular outgoing number when several numbers share one Apple ID.
--json emits one JSON object per line. Human progress and warnings stay on stderr, so stdout remains safe to stream. Pipe finite commands through jq -s when you want one array.
imsg chats --json | jq -s
imsg rpc
imsg completions llmThe JSON schema documents chats, messages, attachments, reactions, polls, scheduled messages, and statistics. The JSON-RPC reference covers the long-running stdio transport used by agents and gateways.
Normal chats, history, watch, send, react, and read-only RPC workflows do not use private frameworks or process injection.
Read receipts, typing indicators, rich sends, message mutation, stickers, polls, and chat management use an injected helper inside Messages.app. They require SIP to be disabled and may be blocked by library validation or private-entitlement checks on current macOS releases. Start with Advanced IMCore, then use the bridge command reference for the full CLI surface and IPC layout.
The complete guide lives at imsg.sh. Useful entry points include install, permissions, history, watch, send, attachments, Linux, and troubleshooting.
make lint
make test
make buildIMsgCore contains the reusable Swift core, imsg contains the CLI, and IMsgHelper contains the optional injected helper. The package uses Swift 6 and targets macOS 14 or newer.
MIT. See LICENSE. Not affiliated with Apple; iMessage and SMS are trademarks of their respective owners.