What is imsg CLI? The Programmatic Gateway to iMessage
1. Solving a Specific Itch
"Every once in a while I stumble on a project that solves a very specific itch in a surprisingly elegant way. imsg is one of those."
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.
Programmatic Access
List chats, fetch history, and monitor incoming messages directly from your terminal or scripts.
JSON-First
Everything is emitted as clean JSON, making it trivial to plug into custom tooling or AI agents.
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.
Read-Only Database Access
Incoming messages are fetched directly from chat.db in read-only mode. This ensures that the tool never risks corrupting your primary message database.
AppleScript for Sending
Rather than using private APIs that could break with every macOS update, imsg leverages official AppleScript hooks to send messages. It's stable, supported, and safe.
Data Normalization
It handles the boring details that developers hate: E.164 phone number normalization, attachment metadata extraction, and multi-participant thread grouping.
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.
Swift Developer Note
You can pull IMsgCore directly into your own macOS app or background helper. This allows you to treat Messages as just another data source—like a REST API or a local JSON file—within your native Swift code.
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.
5. The AI-Native Social Graph
The true potential of imsg is realized when paired with AI agents. In the "OpenClaw" ecosystem (formerly Moltbot), imsg acts as the sensory input and motor output for autonomous agents.
By transforming a messy database into a stream of structured JSON-RPC events, the tool allows AI models to understand who they are talking to, recall previous context across weeks of history, and respond with human-like timing and awareness. It’s the infrastructure required for an **AI-native social graph**.
6. Quick Setup Guide
Getting started with imsg is straightforward thanks to its availability via Homebrew.
# 1. Install via Homebrew
brew install steipete/tap/imsg
# 2. Grant permissions in System Settings
# Full Disk Access for Terminal/iTerm
# 3. Test your first command
imsg chats --limit 5
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.
Remote/SSH Variant
You can even run imsg on a remote Mac (e.g., a dedicated Mac Mini) and communicate via an SSH wrapper:
#!/usr/bin/env bash
exec ssh -T bot-mac-mini imsg rpc "$@"⚠️ 8. Security & Permissions
Because imsg needs to read the Messages database, it requires elevated permissions on macOS:
- 01.Full Disk Access: Required for accessing
~/Library/Messages/chat.db. - 02.Automation: Required when sending messages, to allow
imsgto control the Messages app via AppleScript.
9. Frequently Asked Questions
Ready to experiment?
Find the source code and full documentation on GitHub: github.com/moltbot/imsg.
Build smarter, automate deeper, and bridge the gap between your conversations and your code.
