imsg CLI
imsg is a macOS command-line tool: an agent reads Messages chats, watches for new messages and sends iMessage and SMS.
- 1,408 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The tool reads personal conversations from Messages and `imsg send` sends messages on behalf of the Mac owner.
- The terminal gets Full Disk Access, which is broader than one database needs.
Install
- Works in
Manual install
brew install steipete/tap/imsgThe Homebrew command from the Install section. macOS 14 or newer is required.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The tool reads personal conversations from Messages and `imsg send` sends messages on behalf of the Mac owner.
- The terminal gets Full Disk Access, which is broader than one database needs.
This is third-party code. Review the repository files before installing.
What it does
imsg is written in Swift. It opens the local database `~/Library/Messages/chat.db` read-only and sends messages through Messages.app automation. The `chats`, `history`, `watch` and `send` commands print line-delimited JSON with the `--json` flag, which suits `jq` and agents. `imsg watch` follows the database and reports new messages, edits, unsends and reactions. The `imsg rpc` command starts a long-running JSON-RPC interface over stdio, and `imsg completions llm` prints help in a model-friendly form. The terminal needs Full Disk Access to work, and sending also needs Automation permission for Messages.
Who it is for. Mac users who want an agent to read their own iMessage conversations and reply on request.
Good fit when
- An agent must find a meeting agreement in Messages history and summarize it.
- A script must react to incoming messages in a stream, for example logging them.
- A short notification must go out over iMessage or SMS from an agent task.
- A chat history with attachments must be exported to JSON for analysis.
Not a fit when
- You have no Mac: the tool needs macOS 14 or newer, and on Linux it reads a copied database.
- Security rules forbid giving the terminal Full Disk Access.
- You must pick the outgoing number when several share one Apple ID: `imsg send` cannot do that.
Example request
List the ten latest chats with `imsg chats --limit 10`, then find messages about tickets in one of them.Limitations
macOS 14 or newer, Full Disk Access for the terminal and Automation permission for Messages are required to send. Contacts access optionally adds names. For SMS, Text Message Forwarding is enabled on the iPhone. Linux builds read only a copied `chat.db` and do not connect to iMessage. With several numbers on one Apple ID the outgoing number cannot be chosen. Over SSH, contact names resolve only if the SSH service has disk access. The last commit dates from November 2026.
How to disable. Remove the tool with `brew uninstall imsg`. In macOS settings, revoke Full Disk Access and Messages automation for the terminal if you granted them only for imsg.
FAQ
How do I install imsg?
Run `brew install steipete/tap/imsg` and check `imsg --version`. Signed builds are in GitHub Releases.
Which permissions are needed?
Full Disk Access to read the database. Sending and tapbacks also need Automation for Messages. Contacts access is optional.
How do I receive new messages?
The `imsg watch --chat-id 42 --reactions --json` command prints events line by line. For a long session there is `imsg rpc`.
Does it run on Linux?
Partly: the build reads a `chat.db` copied from macOS. Sending messages and connecting to iMessage from Linux is not possible.
How do I send a message?
Run `imsg send --to "+14155551212" --text "on my way"`. Attachments and tapbacks have their own documentation pages.
Discussion
No questions or reviews yet.
Related
CLI toolsAn MCP server for macOS: an agent reads, searches and sends messages in the Messages app on your Mac
A Slack CLI and skill: the agent reads channels and threads and searches messages and files, and drafts or sends only when you ask
Claude-to-IM
claude-to-im
A bridge between Claude Code or Codex and messengers: talk to the agent from Telegram, Discord, Feishu, QQ or WeChat
A Go utility with JSON output: an agent reads WhatsApp chats, searches messages and contacts and sends texts from your number
GreenBubbles reads your WeChat history on a Mac, searches chats and feeds agents for cited notes. The key is captured by hand.
OpenKakao
OpenKakao CLI
macOS CLI that lets an agent read and send messages in an already signed-in KakaoTalk through Accessibility and verify by screen
README in short
A Swift 6 tool reads the local Messages database and calls Messages.app AppleScript. NDJSON and JSON-RPC output is built for scripts and agents, with docs at imsg.sh.