What is imsg CLI? The Programmatic Gateway to iMessage

1. Solving a Specific Itch

In the rapidly evolving landscape of automation and AI, the missing link has often been personal communication. While APIs exist for Slack, Discord, and Telegram, iMessage has remained a walled garden on macOS, until now.

imsg is a small but powerful Swift CLI that provides programmatic access to iMessage and SMS on macOS, backed by the native Messages app database. It represents a shift from "hacking" the system to "respecting" it, providing a stable bridge between your chat history and your custom tools.

2. What is imsg?

At its core, imsg is a command-line tool designed for developers who need to treat iMessage as a data source. Whether you want to list your chats, pull deep message history, or "watch" conversations in real time, imsg makes it possible with a few keystrokes.

What makes it truly interesting is the ability to emit everything as JSON. This means you can plug your Messages straight into your own tooling, scripts, or agents without the "weird hacks" typical of previous iMessage automation attempts.

3. How It Works Under the Hood

The genius of imsg lies in its respect for the macOS ecosystem. It doesn't attempt to reverse-engineer iMessage's encryption or private cloud protocols. Instead, it works with the data your system already has.

4. IMsgCore: The Engine behind the CLI

For those building more complex macOS applications, the project isn't just a binary. It's powered by IMsgCore, a modular Swift library.

This dual-layered approach (CLI for shell users, Library for app developers) makes imsg one of the most versatile tools in the macOS automation toolkit.

6. Quick Setup Guide

Getting started with imsg is straightforward thanks to its availability via Homebrew.

7. Advanced Configurations

For AI agent gateways (like OpenClaw), imsg runs in RPC mode. This spawns a JSON-RPC session over stdio, allowing the gateway to pipe events back and forth continuously.

#!/usr/bin/env bash
exec ssh -T bot-mac-mini imsg rpc "$@"

9. The Command Surface in Practice

The thing that makes imsg pleasant to work with is that its command set is small enough to hold in your head. There is no plugin system to learn and no configuration file to write before you can get an answer out of it. Six commands cover essentially everything most people need.

NDJSON, and why the stream discipline matters

The JSON output is newline-delimited: one object per line, emitted as it becomes available rather than buffered into a single array at the end. Crucially, human-readable progress messages and warnings are routed to stderr, which leaves stdout clean for piping. That sounds like a trivial detail until you have spent an afternoon debugging a pipeline that broke because a tool printed a status banner into the middle of your data stream.

In practice it means you can do something like imsg chats --json | jq -s to collapse the stream back into a single array, or feed imsg watch --json straight into a long-running process without any parsing ceremony at all. For agents, the RPC transport does the same job with a persistent session, so a gateway can keep a single process open and exchange commands and events continuously instead of paying process-spawn cost on every message.

10. Platform Support & Requirements

The requirements are modest but non-negotiable. You need macOS 14 or newer, Messages.app signed in, and an existing ~/Library/Messages/chat.db. Building from source needs Swift 6. Signed macOS builds are published to GitHub Releases, and Homebrew is the simplest route for everyone else.

Contacts access is genuinely optional. Without it the tool still works perfectly well, it simply leaves names unresolved and hands you E.164 phone numbers. If you are running over SSH, contacts can still be resolved through the Mac's read-only address book provided the SSH service itself has been granted Full Disk Access, which is a detail worth remembering when you inevitably discover that your headless Mac Mini is returning numbers instead of names.

There are also read-only Linux builds for x86_64. These do not connect to iMessage and cannot send anything; they read a chat.db that you have copied across from a Mac. That is useful for analysis and archival work, and useless for automation, so set your expectations accordingly. The project is MIT licensed.

How watch actually works

Real-time monitoring is the part most home-grown iMessage scripts get wrong. Naive implementations poll the database on a timer, which is either laggy or wasteful depending on the interval you pick. imsg watch follows filesystem events on the database and its write-ahead log, with a polling fallback for the cases where macOS drops events or rotates the sidecar files out from under it. All read commands open SQLite in read-only mode, so there is no realistic path by which the tool corrupts the database it is reading.

11. Limitations and the SIP Question

It is worth being clear about what imsg cannot do, because the boundary is a deliberate design decision rather than an oversight.

The supported surface is built on AppleScript for writes and read-only database access for reads. That combination is stable across macOS updates, but it also caps what is reachable. A set of advanced capabilities does exist behind a bridge, covering things like read receipts, typing indicators, polls and programmatic chat creation, but these require System Integrity Protection to be disabled and may still be blocked by library validation on current macOS versions.

There is one more practical quirk. Because imsg send drives Messages.app's AppleScript interface, it cannot force a specific outgoing number when several numbers share a single Apple ID. If you run multiple lines through one account, the message goes out on whichever one Messages.app decides to use. That is a limitation of the supported interface, not of the tool.

12. Where imsg Fits in the Agent Stack

The reason imsg gets more attention than a well-built CLI normally would is that it sits at a specific structural gap. Personal AI agents that live on your own hardware need a channel to reach you through, and the obvious candidates all carry a cost. Slack and Discord mean your assistant lives somewhere you associate with work. Telegram and WhatsApp mean a bot account and a third party in the middle. iMessage is the channel most people in the UK and US already leave open by default, and until recently it was the one channel no tool could touch cleanly.

That is why the project has ended up as part of the plumbing under OpenClaw, the personal-agent framework formerly known as Moltbot and, before that, Clawdbot. The RPC transport is precisely what a gateway needs: one persistent process, structured events in, structured commands out, no polling loop to write yourself. If you want to see how it plugs together end to end, our iMessage setup guide walks through the gateway configuration, and the project overview covers the wider architecture.

Sensible things to build with it

• A read-only digest. The lowest-risk starting point. Point imsg history at a busy group thread, summarise it, and send the summary somewhere else entirely. No write permissions, no chance of the agent embarrassing you.
• Archival and search. Export to NDJSON, index it, and finally have a searchable record of a decade of conversations that Spotlight has never handled well.
• Alerting. Use watch to trigger on specific senders or keywords, and route those to a pager, a smart light, or anything else that will actually get your attention.
• Assisted replies. The genuinely useful and genuinely risky one. Draft rather than send, at least until you have watched it behave for a fortnight.