← Back to tools

imsg

Command-line interface for Apple Messages on macOS

Homepage Repository
Productivity System & Monitoring macos Swift MIT

Description

imsg is a macOS CLI for Apple Messages.app that enables agents and scripts to list chats, view message history, stream new messages in real-time, and send text or attachments via iMessage or SMS. It uses AppleScript for sending (no private APIs) and read-only SQLite access for message retrieval.

Install

sourcegit clone https://github.com/steipete/imsg && cd imsg && make build

AI Summary

macOS CLI for Apple Messages providing chat listing, message history retrieval, real-time message streaming, and iMessage/SMS sending with attachment support. Uses read-only DB access and AppleScript for sending.

Capabilities

  • + List recent conversations with metadata (chat ID, name, service, last message time)
  • + Retrieve message history with filtering by chat, date range, and participants
  • + Stream new messages in real-time via filesystem event watching
  • + Send text messages and file attachments via iMessage or SMS
  • + Phone number normalization to E.164 for reliable contact lookup
  • + Attachment metadata output including MIME type, filename, path, and missing status
  • + JSON output mode for all commands for scripting and agent integration
  • + SMS relay support when iPhone Text Message Forwarding is enabled

Use When

  • → An AI agent needs to read or send iMessages programmatically
  • → Monitoring incoming messages in real-time for automated responses
  • → Searching message history from the command line
  • → Sending notifications or alerts via iMessage from scripts
  • → Building automation workflows around Apple Messages

Avoid When

  • x Running on non-macOS platforms
  • x Working without Full Disk Access permission (needed for chat.db)
  • x Need to interact with WhatsApp, Signal, or other non-Apple messaging services

Usage Patterns

List recent chats

imsg chats --limit 20 --json

Lists the 20 most recent conversations in JSON format

View message history

imsg history --chat-id CHAT_ID --limit 50 --json

Retrieves the last 50 messages from a specific chat

Stream new messages

imsg watch --json

Watches for and streams new incoming messages in real-time

Send a text message

imsg send --to "+1234567890" --text "Hello!"

Sends an iMessage to the specified phone number

Send a file attachment

imsg send --to "+1234567890" --file /path/to/image.png

Sends a file attachment via iMessage

Input / Output

stdin: Not typically used
stdout: Human-readable text or JSON (with --json flag)
stderr: Error and status messages
Exit codes:
0 Success
1 Error

Typical Pipelines

imsg chats --json | jq ".[0].id" | xargs -I{} imsg history --chat-id {} --limit 10 --json
imsg watch --json | jq 'select(.is_from_me == false)'

Related Tools

wacli alternative

wacli provides similar messaging CLI capabilities for WhatsApp
View AGENTS.md for imsg