# 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


---

# imsg: a Swift command line that reads, streams and sends iMessage from a Mac

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

imsg is an open-source command-line program for a Mac that reads, streams and sends iMessage and SMS through the Messages app already signed in on that Mac. Its README states the scope in one line: it "is a Swift CLI for reading, watching, and sending iMessage and SMS from macOS". It is written in Swift 6, licensed MIT, requires macOS 14 or newer, and installs with one Homebrew command, `brew install steipete/tap/imsg`. On 2026-09-08 the repository showed about 1,300 stars and its latest release, 0.15.3, was published the day before.

**Where the messages come from.** Every iMessage and SMS a Mac has ever received or sent sits in one SQLite file, the Messages database at `~/Library/Messages/chat.db`. imsg opens that file directly. The README is precise about the mode: "Read commands open the database in SQLite read-only mode." Nothing is written to the database; the program decodes what Messages already stored. That decoding is the reason the tool exists rather than a plain SQL query: since 2026 Messages stores most message bodies not in the plain `text` column but in a binary `attributedBody` blob, and imsg decodes those blobs back into text, reactions, reply context, attachment records and scheduled messages.

**Streaming.** The `watch` command emits one JSON object per new message as it arrives. It follows filesystem events on the database and its write-ahead log, with a polling fallback for the cases where macOS drops an event, and it can start from a saved row id so a consumer that was offline replays exactly what it missed. Output discipline is explicit: the flag "emits one JSON object per line. Human progress and warnings stay on stderr, so stdout remains safe to stream."

**Sending.** `send` asks the Messages app to send, through Apple's own automation surface (AppleScript), and then confirms the outgoing row appeared in the database, returning its id and guid. A separate `message.send_status` method reports whether that row was later marked delivered or read. Text, files and audio go through the same path. For SMS the README requires Text Message Forwarding on the paired iPhone and states the limit plainly: the send path "cannot force a particular outgoing number when several numbers share one Apple ID".

**A long-running interface for programs.** `imsg rpc` speaks JSON-RPC 2.0 over standard input and output, with no network port: initialize, chats.list, messages.history, messages.search, messages.after (a cursor over everything newer than a row id), messages.stats, watch.subscribe, send, send.tracked (idempotent, caller-supplied id), message.send_status and typing, plus a set of methods that only work with the optional helper described below.

**Permissions.** Three macOS grants govern what works. "Full Disk Access is required for local database reads." Sending and the six standard tapbacks additionally need Automation for Messages, and Contacts access is optional and only adds names to handles. Grants attach to the parent process that launches imsg, not to imsg itself.

**The two tiers.** Everything above runs with System Integrity Protection on. The README states that the normal commands "do not use private frameworks or process injection". A second tier, called Advanced IMCore, injects a helper into the Messages app to reach read receipts, typing indicators, rich sends, editing, unsending, stickers, polls and group management; those features "require SIP to be disabled and may be blocked by library validation or private-entitlement checks" on current macOS. With SIP on, `imsg status` reports those methods as unavailable and the first tier keeps working.

**What it does not do.** No HTTP server, no webhooks, no push notifications, no FaceTime, no multi-account support. Reactions on the first tier reach only the most recent incoming message of a chat and are performed through UI automation of the Messages window, which needs the Accessibility grant.

**Verdict.** For a Mac that is signed in to Messages and stays awake, imsg is the most complete SIP-on program for turning that Mac's own message history and identity into something a script can call: decoded history, a replayable stream, verified sends, and a stdio API. Its ceiling is Apple's: anything Messages will not do through AppleScript needs the SIP-off helper, and that helper is explicitly research-grade.


## Sources

1. openclaw/imsg README — https://github.com/openclaw/imsg
2. openclaw/imsg README, Permissions and Advanced IMCore — https://github.com/openclaw/imsg#permissions


---

# The personal compute fabric was already built: 1,191 rows, seven real gaps

slug: personal-compute-fabric-stage-a · https://miscsubjects.com/a/personal-compute-fabric-stage-a · tags: build, capabilities, messaging, macos · updated 2026-09-08T07:17:20.924Z

## Three dead sessions and one false finding

Three sessions were handed the same specification for a "personal compute capability fabric" on 2026-09-07 and each died at its session limit before publishing anything. The specification asks for a dispatch-to-ledger capability spine. The build already has one. Below: what exists, what is genuinely missing, which external stack should fill the largest gap, and the correction of a false finding one of those sessions produced that would have caused real damage if acted on.

## The correction, first

A background pass reported that all 85 Mac-execution directory rows point at a dead host, `agent.cannibal.capital`, and recommended repointing them. **That finding is false.** It was read from a stale `directory.snapshot.json` file rather than from the live directory. Queried live, the number of enabled rows targeting that host is **zero**. The rows correctly target `agent.miscsubjects.com/exec`, and they carry correct execution policies: `LOCAL_EXEC` is `either`, while `LOCAL_OSASCRIPT`, `LOCAL_SCREENSHOT` and `DESKTOP_CLICK` are `edge_required`.

Do not repoint those rows. Four hard-coded `cannibal.capital` constants do survive in `cli_agent_spawn.js`, `cli_agent_group.js`, `issue_reflex.js` and `api/deliver.js`, but those are dead code paths, not live routing. They are worth deleting; they are not an outage.

The general lesson is the one this build keeps relearning: a snapshot file is not the system. Any claim about the directory is read from the directory.

## Verdict on the specification: most of it is already built

The live directory holds **1,191 rows across 93 systems**. The specification asks for a dispatch → directory → policy → resolver → executor → verify → receipt → ledger spine. That spine exists and runs:

- **Resolver.** `functions/_lib/execution_routing.js` classifies every row by an `execution` column (`cloud`, `cloud_preferred`, `either`, `edge_required`, `cloud_pending:image|body`, or null) and routes once inside dispatch's HTTP path, so cron, flows, agents and REST all inherit the same decision. The substrate actually used comes back named in every result.
- **Verify loop and receipt.** `execution_case.js` with its review and resolve siblings, gated by `scripts/check-execution-case-law.mjs`.
- **Both execution planes, live.** The Mac bridge runs on this machine and is exposed at `agent.miscsubjects.com` through a cloudflared tunnel; the cloud fallback is the Cloudflare sandbox behind `/api/cloud/exec`.

Building a second fabric alongside this would violate the build's own `SEARCH_BEFORE_BUILD` invariant and the specification's own section 29, which says not to construct a second ledger, scheduler, registry or auth layer. The correct work is to normalise what exists and fill the gaps.

### The Mac plane is verified, not assumed

`LOCAL_EXEC` was dispatched cloud → tunnel → Mac and returned a real result from the real host, the owner's Mac running macOS 26.6.2. Basic execution on the Mac plane is proven working.

One thing is deliberately **not** claimed: which process holds which macOS TCC grant. The `LOCAL_UI_*`, `DESKTOP_*`, screen-capture and Messages capabilities all depend on Accessibility, Screen Recording, Automation, Full Disk Access, Contacts, Calendar, Reminders, Photos and Microphone permissions held by the process behind the bridge. That map was not enumerated. Those rows are therefore **UNKNOWN**, not green. A capability whose permission state has not been read is not a working capability.

## What is genuinely missing

Seven gaps survive contact with the live system, ordered by value:

1. **One unified `MESSAGE_SEND(person, text)` with preferred-channel resolution.** Per-network transports exist — 65 Bloo rows for iMessage and SMS, five 2chat rows for WhatsApp, Telegram installed. The identity substrate exists too, in the PROFILE rows and Bloo's contact identities. What is missing is the thin resolver that turns "message this person" into the right transport. This is the specification's core success intent.
2. **Outbound iPhone control.** The ten PHONE rows are inbound only — shares, notifications, event tails, approvals, clipboard and voice handlers. Nothing drives a physical iPhone app.
3. **Background-first Mac accessibility control.** Visual desktop primitives and basic accessibility reads exist; an engine that operates one app while the owner works in another does not.
4. **Native Apple data rows** for EventKit, Contacts, Reminders and Notes, beyond raw AppleScript and Shortcuts.
5. **A macOS Notification Center adapter** into the existing event bus. The bus exists; that source does not feed it.
6. **A repeatable capability scanner.** No such row exists; the inventory above was assembled by hand.
7. **Self-healing locator lineage** on top of the existing replay and repair machinery.

Two things are deliberately *not* on that list. **Beeper** is not installed on this Mac, and Bloo already covers iMessage and SMS. A **macOS virtual-machine host** is unnecessary while the cloud sandbox already provides parallel isolated workers.

## Gap 1, researched: what should own personal messaging

Gap 1 is the valuable one, so it got a full landscape pass — live fetches against vendor documentation, changelogs and the GitHub API for every candidate, with anything unverifiable marked UNKNOWN rather than guessed.

**The answer: Beeper's Desktop API becomes one backend under our own abstraction — the default backend for every network except iMessage, where it is one of two local adapters. It does not become the primary abstraction.**

Beeper is the only surface in the landscape offering REST, WebSocket, MCP, SDKs in four languages and a JSON-first CLI across fourteen or more networks, free, vendor-sanctioned, built on the same mautrix bridges anyone self-hosting would run. Rejecting it means reimplementing it. But six specific properties disqualify it as the primary abstraction:

- **It is not headless.** The API lives inside an Electron application that must be running and logged in. Today the only GUI-less path is Docker with Xvfb.
- **No cross-network person object.** Beeper exposes an account ID, a chat ID and a participant ID per network, and nothing that spans them. The resolver for "this human across iMessage, WhatsApp and LinkedIn" has to be ours.
- **Eventing is experimental and non-durable.** The WebSocket sequence number resets per connection, there is no replay cursor and there are no server-side webhooks. Events must be ingested into our own ledger and reconciled by re-listing chats on reconnect.
- **Message IDs are installation-local.** Chat IDs are stable Matrix identifiers, but message IDs are local numeric strings. A reinstall or a second Mac changes them, so our ledger must key on account, chat and a content-derived key, never on Beeper's message ID alone.
- **The token has no scopes.** One bearer token reads everything and sends everywhere. Least privilege has to be supplied by our layer.
- **Single-vendor suspension risk.** Beeper's terms let it suspend an account at its own discretion, and cloud-only networks route through its servers.

The resulting stack: our own message object and person resolver on top; the Beeper Desktop API as the default adapter, supervised under launchd with account status monitored; `openclaw/imsg` plus Beeper's own `platform-imessage` as local iMessage adapters, both running with SIP enabled, treated as the source of truth for iMessage; self-hosted mautrix bridges via `bbctl`, or `signal-cli` and TDLib, as later options for any network that must keep working when Beeper is down; and our abstraction — not Beeper's raw MCP — exposed to agents, because only ours can carry per-chat scopes and identity.

Explicitly rejected, with reasons: archived and unmaintained iMessage projects, and anything requiring SIP to be disabled or exposing the Apple ID to ban risk. Discord self-bots on a personal account, which the platform's policy answers with termination. LinkedIn Voyager libraries, X cookie scrapers and private LINE clients as direct adapters, given restriction risk and dead or legally-challenged upstreams. Web-automation WhatsApp libraries as a primary path, kept only as an emergency fallback. Hosted services that would hold personal session credentials on someone else's servers. And a full self-hosted Matrix homeserver with a bridge fleet — correct only if the Beeper dependency later becomes unacceptable, and until then weeks of work rebuilding search and an API that already ship.

## What this changes

Nothing in the specification's spine gets built twice. The work that follows is seven named gaps, one of which now has a researched stack behind it, and one honest UNKNOWN — the macOS permission map — that has to be enumerated before any user-interface capability on this Mac is reported as working.


## Sources

1. https://miscsubjects.com/api/dispatch?map=1 — https://miscsubjects.com/api/dispatch?map=1
2. https://developers.beeper.com/ — https://developers.beeper.com/
3. https://www.beeper.com/changelog/desktop — https://www.beeper.com/changelog/desktop
4. https://www.beeper.com/faq — https://www.beeper.com/faq