Vibeleaderboard
← Back to Tools
Index / tool

imsg

github.com/steipete/imsg
Visit imsg.to
Category
Developer Tools
Rank
No. 611Tools index
Pricing
Open Source
Type
TOOL
Builder
@steipete
GitHub
1.3k stars
Latest release
v0.15.3
Date

About

A command-line tool for macOS that allows programmatic access to Apple's Messages.app to send, receive, and stream iMessages and SMS. Enables automation and AI agents to interact with Messages without using private APIs.

What it does

imsg turns the local Messages data store into script-friendly records and event streams. It reads conversations through SQLite, watches filesystem changes for new activity, and delegates ordinary outgoing text, files, and tapbacks to Messages automation.

Why it's ranked here

A strong choice for local automation because it combines read-only database access, clean streaming output, and a persistent stdio protocol. Its careful delivery states and cursor handling address real automation hazards. The Apple-specific permissions and fragile advanced bridge narrow its appeal.

What's good

JSON output stays parseable because diagnostics go to standard error. Watches combine filesystem events with polling, support resumable cursors, and report bounded-buffer overflow. Sends distinguish safe retries from uncertain delivery, while history recovers rich-text bodies and coalesces link-preview companion rows.

Tradeoffs

Useful macOS reads require Full Disk Access, while sending needs Messages automation permission. SMS also depends on forwarding from a paired iPhone. Linux only inspects copied databases. Rich sends, typing, read receipts, polls, mutations, and chat management rely on an injected helper, disabled system protection, and private behavior that current releases may block.

How to use it well

Use it for local archives, message-driven agents, dashboards, notifications, and controlled sending from a dedicated Mac. Prefer stable JSON or the long-running stdio protocol, persist watch cursors per database generation, and treat uncertain sends as non-retryable. It does not replace a cross-platform live Messages client.

Technical notes+

README.md describes three Swift components: IMsgCore for reusable logic, imsg for the CLI, and IMsgHelper for optional injection. docs/rpc.md specifies strict JSON-RPC 2.0 over newline-framed stdio, a 128-request admission bound, separate FIFO mutation and concurrent read lanes, typed delivery dispositions, and database-generation-aware watches. docs/watch.md documents kqueue observation of the SQLite database and WAL sidecars, polling recovery, bounded subscriber queues, overflow cursors, and per-source ordering. docs/send.md details bounded /usr/bin/osascript children, attachment staging, post-send database verification, narrow SMS fallback, and ghost-row detection. Makefile builds the universal Swift executable and an optional arm64e injected dylib.

Observed

License
MIT
Primary language
Swift 6
Install surface
Homebrew tap, signed macOS release binaries, source builds through Swift Package Manager, and Linux x86_64 release archives
Interfaces
Command-line interface, NDJSON output, and JSON-RPC 2.0 over stdio
Platform support
macOS 14 or newer for full operation; Linux x86_64 supports read-only inspection of copied Messages databases
Runtime architecture
Default reads use SQLite read-only access, ordinary sends use Messages AppleScript automation, and advanced features use an optional injected helper

Read from README.md, Makefile, docs/rpc.md, docs/json.md, docs/send.md, docs/index.md, docs/chats.md, docs/linux.md, docs/stats.md, docs/watch.md, docs/bridge.md, docs/groups.md, docs/history.md, docs/install.md, docs/RELEASING.md.

What it can do

  • Send iMessages programmatically

    Recipient contact and message text → Sent iMessage

  • Send SMS messages programmatically

    Phone number and message text → Sent SMS message

  • Receive and retrieve iMessages

    Messages database query → Retrieved iMessage content

  • Receive and retrieve SMS messages

    Messages database query → Retrieved SMS content

  • Stream real-time message events

    Stream monitoring request → Live message event data

  • Send messages with file attachments

    Recipient, message text, and file attachment → Sent message with attached file

Tags

cliimessagesmsmacosautomationmessagingapplescript

Tech Stack

Swift

Comments (0)

No comments yet

Editorially curated, with community endorsements as a secondary signal. Corrections welcome.