# platform-imessage: Beeper's Swift library that drives the Messages app through Accessibility

slug: platform-imessage · https://miscsubjects.com/a/platform-imessage · category: reference · tags: reference, imessage, mac, messaging, accessibility · updated 2026-09-08T20:13:35.726Z

platform-imessage is an open-source Swift library and command-line program from Beeper, the multi-network chat company, that automates the Messages app on a Mac. Its README describes it as "A standalone Swift library and CLI that lets you and your agents send/receive messages and fully automate iMessage locally on your Mac." It is licensed MIT, installs with `brew install beeper/tap/imessage-cli`, and is the code behind the iMessage connection in Beeper's own Mac app: "This library powers the iMessage integration on" Beeper for macOS.

**Two mechanisms, one program.** For reading, it opens the Messages database (`~/Library/Messages/chat.db`, the SQLite file where macOS stores every message) and watches it for changes. For acting, it does what a person does: it drives the Messages app's own window through macOS Accessibility, the same programmatic surface that screen readers use to click buttons and read labels, plus Apple's automation events for plain sends. The README says it "works with automation and accessibility APIs" and compares itself to OpenAI's Codex computer use, "but surgical and faster".

**Why that matters.** Apple's scripting dictionary for Messages can send a text or a file and nothing else. Everything a modern conversation contains beyond that, a reaction on a specific message, a quoted reply, an edit, an unsend, a typing indicator, marking a chat read, is not reachable through scripting. The other established route to those features, BlueBubbles, reaches them through a Private API helper that only loads when System Integrity Protection is off; the README's feature table marks each of those rows and footnotes them: "BlueBubbles supports this through its Private API helper, which requires disabling SIP." platform-imessage reaches the same rows with SIP on, by operating the real window.

**What the command line does.** `chats`, `chat`, `messages`, `message`, `search` read history with contact-resolved names, tapbacks, stickers, mentions, replies and edit history. `send` and `send-file` send to an address or an existing chat; `create-chat` starts a new direct or group chat with people never messaged before. `reply` and `reply-file` send quoted replies to a message id (or to `latest`, `latest-1`). `react` and `unreact` add or remove a tapback on any message by id, including arbitrary emoji. `edit` and `undo-send` change or retract a sent message inside Apple's time windows. `typing` turns the typing indicator on or off; `mark-read`, `mark-unread`, `mute`, `unmute`, `notify-anyway` and `delete-chat` manage a chat; `activity-status` reports whether the other party is typing and their Do Not Disturb state; `load-attachment` forces an offloaded attachment to download. `start-watching` streams database changes as events. Output is YAML by default and JSON with `--json`.

**How it avoids fighting the person at the keyboard.** By default it launches a secondary instance of the Messages app and drives that window, so the primary window a person is using is left alone. The flag `--no-use-secondary-instance` turns that off.

**Permissions and limits.** Four macOS grants: Accessibility, Contacts (optional, for names), Messages data (Full Disk Access) and Automation for Messages. The README states what it will not do: "expose more features if you disable SIP, allow automating multiple iMessage accounts, work on Windows/Linux". Group management (rename, add or remove members, leave, photo) and rich sends (effects, subjects, captions) are listed as planned. Only one process may drive the Messages app at a time. There is no HTTP server, no webhook and no push relay; the README's table gives that row to BlueBubbles.

**Fragility.** Because acting means locating message cells in a live window, a macOS release that rearranges the Messages interface can break an action until the library is updated; the project's todo list tracks such fixes per macOS version. Reading is not affected by that, since it comes from the database.

**Verdict.** On a Mac with SIP on, platform-imessage is the only maintained program that reaches reactions on arbitrary messages, quoted replies, edits, unsends, typing and read state. Its cost is the Accessibility route: slower than a database read, dependent on the window layout, and exclusive of any other automation touching the Messages app at the same moment.


## Sources

1. beeper/platform-imessage README — https://github.com/beeper/platform-imessage
2. beeper/platform-imessage README, feature table footnote — https://github.com/beeper/platform-imessage#features