imbridge 0.1.0__tar.gz

imbridge-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+
+# built by helper/build.sh (released wheels include it)
+src/imbridge/helper/*.dylib

imbridge-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 0.1.0 (2026-09-26)
+
+First release.
+
+- Send, reply inline, tapback (the six classics or any emoji), typing indicators, read receipts, and message effects,
+  through a helper injected into Messages.app.
+- Receive new messages, tapbacks and inline replies from `chat.db`, including text that only exists in
+  `attributedBody`.
+- Chat handles: `im.chat(...)` gives a conversation whose `messages()` only yields that chat, and whose `reply()` and
+  `react()` refuse other chats' messages (`WrongChat`). The stream over every chat is `im.all_messages()`.
+- Sending is opt-in per chat: imbridge is read-only until a chat is allowed, inline in code with
+  `IMBridge(allow=[...])` (phone numbers, emails, group names or GUIDs, checked at `start()`) or with `imbridge allow`
+  (which needs a person at a terminal). Sends are rate-limited to 10 a minute per chat and 30 in total, across every
+  imbridge process on the Mac.
+- Chats can be named by a group's display name wherever a chat is expected; a name several chats share is refused.
+- `IMBridge(address=...)` (or `IMBRIDGE_ADDRESS`, or `--address`) says which of your own addresses a program is, for
+  Apple IDs with several numbers: it only sees messages sent to that address and won't send in chats on another
+  (`WrongAddress`). With no address set and messages arriving at several of your phone numbers, imbridge refuses
+  to read or send (`AddressNotChosen`), including when a second number first appears mid-stream.
+- The `imbridge` command: `doctor`, `start`, `allow`, `disallow`, `allowed`, `send`, `reply`, `react`, `chats`,
+  `history`, `watch`.
+- The helper is BlueBubbles' Private API helper (pinned commit) plus four patches: any-emoji tapbacks, a fix for the
+  macOS 26+ crash when replying or reacting while someone is typing, a clang build fix, and imbridge's transport
+  (its own port, a token, line-delimited requests, 1-second reconnects).

imbridge-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

imbridge-0.1.0/NOTICE

@@ -0,0 +1,18 @@
+imbridge
+Copyright 2026 Christian Blandford
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+The helper that imbridge injects into Messages.app is built from the BlueBubbles Private API helper
+(https://github.com/BlueBubblesApp/bluebubbles-helper), Copyright the BlueBubbles contributors, licensed under the
+Apache License, Version 2.0. imbridge builds it at the commit pinned in helper/UPSTREAM and modifies it with the
+patches in helper/patches.
+
+The helper also contains:
+- CocoaAsyncSocket (https://github.com/robbiehanson/CocoaAsyncSocket), public domain (BSD license where public
+  domain is not recognized)
+- ZKSwizzle (https://github.com/alexzielenski/ZKSwizzle), Copyright (c) 2014 Alexander S Zielenski, MIT License
+- CTBlockDescription from CTObjectiveCRuntimeAdditions (https://github.com/ebf/CTObjectiveCRuntimeAdditions),
+  Copyright (c) 2012 Oliver Letterer, MIT License
+
+imbridge is not affiliated with or endorsed by Apple Inc. iMessage and Messages are trademarks of Apple Inc.

imbridge-0.1.0/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.5
+Name: imbridge
+Version: 0.1.0
+Summary: iMessage for Python and AI agents on macOS: send, reply inline, tapback with any emoji, and receive. No server, no Electron.
+Project-URL: Homepage, https://github.com/christianblandford/imbridge
+Project-URL: Issues, https://github.com/christianblandford/imbridge/issues
+Author: Christian Blandford
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: ai-agents,bluebubbles,chatbot,imessage,macos,messages,tapback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# imbridge
+
+**iMessage for Python and AI agents on macOS.** Send messages, reply inline, tapback with *any* emoji, and receive
+everything as it arrives, straight through Messages.app. No server to run, no Electron app, no cloud relay, and no
+way for a bug to message your contacts.
+
+```python
+import asyncio
+from imbridge import IMBridge
+
+ALEX = "+15551234567"  # the one conversation this bot works in
+
+async def main():
+    async with IMBridge(allow=[ALEX]) as im:  # imbridge sends nowhere else
+        chat = im.chat(ALEX)
+        async for message in chat.messages():  # only this chat's new messages, tapbacks and replies
+            if message.text and not message.reaction:
+                await chat.react(message, "👀")  # any emoji, not just the classic six
+                await chat.reply(message, "on it")  # an inline (threaded) reply
+
+asyncio.run(main())
+```
+
+## Why imbridge
+
+- **Nothing to host.** Your agent imports a library. There's no server process, Electron app or web UI. Besides your
+  code, the only moving part is a small helper inside Messages, which talks to your process over a token-protected
+  localhost socket.
+- **It can't spam your contacts.** imbridge sends nowhere until you allow a chat, either in your code or with
+  `imbridge allow`, which only a person at a terminal can run. A chat handle refuses messages from other chats, rate
+  limits stop runaway loops, and with two numbers on one Apple ID it only answers on the one you choose.
+- **Any-emoji tapbacks.** The classic six plus any emoji, as iOS 18 and macOS 15 allow. BlueBubbles' released helper
+  and imsg can only send the classic six.
+- **Real iMessage features.** Inline replies, tapbacks, message effects, typing indicators and read receipts, done by
+  Messages itself rather than by scripting its UI.
+- **Current.** Tested on macOS 27. It fixes a macOS 26+ crash in BlueBubbles' helper when it replies or reacts while
+  someone is typing.
+
+## How it compares
+
+As of September 2026:
+
+| | imbridge | BlueBubbles Server | imsg |
+|---|---|---|---|
+| What you run | a Python library | an Electron app with a REST/WebSocket server | a Swift CLI with a JSON-RPC mode |
+| Send and receive text | ✓ | ✓ | ✓, without disabling SIP |
+| Inline replies and targeted tapbacks | ✓ | ✓ (Private API) | ✓ (its helper) |
+| Send any-emoji tapbacks | ✓ | not in a release | ✗ (it can read them) |
+| Sends only to chats you allowed | ✓ | ✗ | ✗ |
+| Needs SIP disabled | yes | for Private API features | for its helper's features |
+| Latest release | new | 1.9.9, May 2025 | 0.15.x, September 2026 |
+
+If you only need plain text in and out and don't want to touch SIP, [imsg](https://github.com/openclaw/imsg) does
+that well. imbridge is for when your agent needs the whole conversation from Python: replies, reactions and effects.
+
+## How it works
+
+```
+                 localhost socket + token
+your Python  ───────────────────────────────▶  helper inside Messages.app  ──▶  iMessage
+    ▲                                              (calls IMCore directly)
+    │  read-only SQLite
+    └──────────────  ~/Library/Messages/chat.db  ◀──  Messages
+```
+
+- **Sending** goes through a small helper library loaded into Messages. It calls IMCore, Apple's private Messages
+  framework, so a reply or tapback is the same operation as tapping it in the app. The helper is
+  [BlueBubbles'](https://github.com/BlueBubblesApp/bluebubbles-helper) Private API helper with
+  [a few patches](https://github.com/christianblandford/imbridge/tree/main/helper/patches), built from source.
+- **Receiving** reads `chat.db`, Messages' own database, read-only. Tapbacks, inline replies, attachments and group
+  chats come through as structured fields.
+
+## Requirements
+
+- An **Apple Silicon** Mac signed in to iMessage in Messages. Built for macOS 11.5 and later; tested on macOS 27.0.
+- **Python 3.10** or later.
+- **System Integrity Protection disabled**, plus two related settings (below). macOS allows no other way to load a
+  helper into Messages; BlueBubbles' Private API and imsg's helper have the same requirement.
+
+> **Warning:** disabling SIP lowers the security of the whole Mac, not just Messages. If you can, run imbridge on a
+> Mac dedicated to it (an old Mac mini is ideal). While SIP is off, iPhone and iPad apps from the App Store won't open.
+
+## Setup
+
+**1. Let macOS load the helper** (once):
+
+1. Shut down, then hold the power button until "Loading startup options" appears. Choose **Options**, then
+   **Continue**, and pick your user if asked. Then choose **Utilities > Terminal**, run `csrutil disable`, and restart.
+2. In Terminal:
+   ```bash
+   sudo nvram boot-args="-arm64e_preview_abi"
+   sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true
+   ```
+3. Restart again.
+
+**2. Give Full Disk Access** to the app that runs your Python (Terminal, iTerm, VS Code, or your agent's app) under
+System Settings > Privacy & Security > Full Disk Access. imbridge needs it to read `chat.db`.
+
+**3. Install and check:**
+
+```bash
+pip install imbridge
+imbridge doctor   # checks every requirement, including that the helper matches your macOS version
+imbridge start    # loads the helper into Messages (restarting Messages, hidden) and waits until it answers
+```
+
+The first `imbridge start` may ask to let your terminal control Messages, because imbridge quits and relaunches it to
+load the helper. Allow it. To run the latest code instead of a release, use
+`pip install git+https://github.com/christianblandford/imbridge`. That builds the helper, so it needs the Xcode
+Command Line Tools (`xcode-select --install`).
+
+**4. Decide where imbridge may send.** Until you do, it only reads. If your Apple ID has more than one phone number
+(two iPhones, say), also tell each program which number it is with `IMBridge(address="+15550002222")` or
+`IMBRIDGE_ADDRESS`; see [Which of your numbers it answers on](#which-of-your-numbers-it-answers-on). List the chats in
+your code with `IMBridge(allow=["+15551234567", "Family"])`, or allow them once for every program on this Mac,
+including the CLI:
+
+```bash
+imbridge chats                   # find the chat: a phone number, an email, a group's name, or its GUID
+imbridge allow +15551234567      # asks you to confirm
+imbridge allowed                 # what's allowed; `imbridge disallow <chat>` takes one back
+```
+
+## Who imbridge may message
+
+imbridge is built so that a bug in your code, or an agent getting creative, can't message people you didn't choose:
+
+- **The allowlist.** Messages, replies, tapbacks, typing indicators and read receipts only go to allowed chats;
+  anything else raises `SendNotAllowed` before Messages is touched. A chat can be allowed two ways, and both are
+  deliberate:
+  - **In your code:** `IMBridge(allow=["+15551234567", "Family"])` takes phone numbers, emails, group names and chat
+    GUIDs. `start()` checks that each one matches exactly one chat, so a typo fails immediately. A running program
+    can't add chats; there's no `allow()` to call from a loop.
+  - **For every program on the Mac:** `imbridge allow <chat>` asks for confirmation and refuses to run without a
+    terminal, so an agent driving the CLI can't add chats itself.
+
+  Allowing every chat takes a deliberate `allow=ANY_CHAT` in code, or `imbridge allow --any`.
+- **Chat handles.** `chat.messages()` yields only that chat's messages, and `chat.reply()` and `chat.react()` raise
+  `WrongChat` for a message from any other chat.
+- **Rate limits.** At most 10 messages and tapbacks a minute to one chat and 30 in total, counted across every imbridge
+  process on the Mac, or it raises `RateLimited`. You can change them with `IMBridge(max_per_chat=..., max_total=...)`.
+- **Your own messages** are left out of every stream unless you ask for them (`include_from_me=True`), so a bot doesn't
+  answer itself.
+
+### Which of your numbers it answers on
+
+A Mac signed in to your Apple ID receives messages sent to every address on it. With two iPhones on one Apple ID,
+texts to your personal number and texts to your bot's number arrive in the same place, and even in the same chat when
+one person texts both. So tell each program which address it is:
+
+```python
+async with IMBridge(address="+15550002222", allow=["+15551234567"]) as im:   # or IMBRIDGE_ADDRESS=+15550002222
+    ...
+```
+
+- **It only sees messages sent to that address.** Streams and history leave everything else out.
+- **It only sends from that address.** Messages replies from whatever address a conversation is on, so imbridge
+  refuses (`WrongAddress`) to send in a chat that's on another address. It also refuses to reply or react to a message
+  that was sent to another address.
+- **Without an address,** imbridge refuses to read or send (`AddressNotChosen`) while this Mac has recent messages at
+  more than one of your phone numbers. If a second number turns up while a program is running, the stream stops with
+  the same error instead of passing that message on. Use `address=ANY_ADDRESS` to deliberately take every number.
+
+`imbridge doctor` lists the numbers in use, every `Message` and chat has an `address`, and the CLI takes `--address`.
+
+## Python API
+
+```python
+async with IMBridge(allow=["+15551234567"]) as im:
+    chat = im.chat("+15551234567")                        # or an email, a group's name, or a chat GUID
+    guid = await chat.send("hello", effect="confetti")    # returns the new message's GUID
+    await chat.reply(guid, "replying inline")             # a Message or a message GUID
+    await chat.react(guid, "love")                        # love, like, dislike, laugh, emphasize, question
+    await chat.react(guid, "🔥")                          # ...or any emoji
+    await chat.react(guid, "🔥", remove=True)
+    await chat.typing()                                   # typing indicator on; chat.typing(False) turns it off
+    await chat.mark_read()
+    chat.history(50)                                      # latest messages, oldest first
+    async for message in chat.messages(include_from_me=False):
+        ...
+
+    im.chats(20)                                          # recent chats, newest first; each has .can_send
+    im.message(guid)                                      # one message, or None
+    async for message in im.all_messages():               # every chat: be deliberate about who you answer
+        ...
+```
+
+A group's name only works when no other chat shares it; otherwise imbridge refuses and lists the candidates' GUIDs
+(`imbridge chats` shows which is which).
+
+A chat has `guid`, `name`, `is_group`, `participants`, `last_message_at`, `address` (which of your addresses it's
+on) and `can_send`. `IMBridge` also has `send`,
+`reply`, `react`, `typing` and `mark_read` that take a chat or message GUID directly; the same allowlist and limits
+apply. iMessage keeps one tapback per person per message, so a new tapback replaces your previous one.
+
+Every `Message` has these fields:
+
+| field | |
+|---|---|
+| `guid`, `rowid` | the message's ID, and its row in chat.db |
+| `chat_guid`, `is_group`, `chat_name` | where it was sent |
+| `sender`, `is_from_me` | the sender's phone number or email; `None` when you sent it |
+| `text`, `date`, `service` | the text (decoded from `attributedBody` when needed), a UTC datetime, and `iMessage`/`SMS`/`RCS` |
+| `reply_to` | the GUID of the message this is an inline reply to |
+| `reaction` | set when the row is a tapback: `kind` (`love`…`question`, `emoji`, `sticker`), `emoji`, `removed`, `target_guid`, `target_part` |
+| `attachments` | each with a `path` on disk, `mime_type` and `name` |
+| `address` | which of your addresses it was sent to (or, for your own messages, sent from) |
+
+**Options.** `IMBridge(allow=..., address=..., max_per_chat=10, max_total=30)` are covered above. `inject=True` loads the helper
+into Messages whenever none answers; pass `inject=False` if something else manages Messages. `poll_interval` (default
+0.5 seconds) sets how often streams check for new messages. Reading (streams, `history`, `chats`, `message`) only
+touches `chat.db`, so it works without the helper.
+
+**Errors.** `SendNotAllowed` means the chat isn't allowed. `RateLimited` means a limit was hit. `AddressNotChosen`
+means this Mac gets messages at several of your phone numbers and the program hasn't said which it is. `WrongAddress`
+means a chat or message is on another of your addresses. `WrongChat` means a
+chat was handed another chat's message. `ChatNotFound` means no existing conversation matches. `HelperError` means the
+helper refused or failed; its subclasses are `HelperNotConnected` and `HelperUnauthorized`. `FullDiskAccessError`
+means `chat.db` can't be read.
+
+**Effects:** `slam`, `loud`, `gentle`, `invisible_ink`, `echo`, `spotlight`, `balloons`, `confetti`, `love`, `lasers`,
+`fireworks`, `celebration`, `shooting_star`.
+
+**Environment variables:** `IMBRIDGE_ADDRESS` is the default `address` (`any` for `ANY_ADDRESS`). `IMBRIDGE_PORT` sets the port the helper dials (default 45700 for the first user account on
+the Mac, one higher for each further account). `IMBRIDGE_HELPER` loads a helper dylib other than the bundled one.
+
+## Command line
+
+```bash
+imbridge doctor                        # check this Mac's setup
+imbridge start                         # load the helper into Messages
+imbridge allow CHAT | --any            # let imbridge send to a chat (asks you to confirm)
+imbridge disallow CHAT | --any
+imbridge allowed
+imbridge send +15551234567 "hello" [--reply-to GUID] [--effect confetti]
+imbridge reply GUID "inline reply"
+imbridge react GUID 🔥 [--remove]
+imbridge chats [-n 20] [--json]
+imbridge history +15551234567 [-n 20] [--json]
+imbridge watch [--chat CHAT] [--json] [--from-me]    # stream new messages; --json prints one object per line
+imbridge <command> --address +15550002222           # start, send, reply, react, history and watch take --address
+```
+
+`send`, `reply` and `react` print the new message's GUID. They follow the same allowlist and rate limits as the
+library.
+
+## Using it with an AI agent
+
+- **As a library**, inside your agent's loop, like the example at the top.
+  [examples/ping_bot.py](https://github.com/christianblandford/imbridge/blob/main/examples/ping_bot.py) is a runnable
+  bot for one chat.
+- **From the shell**, for any agent that can run commands: it reads new messages from
+  `imbridge watch --chat CHAT --json` and answers with `imbridge reply GUID "..."` or `imbridge react GUID 👍`. Allow
+  the chats it may use beforehand; it can't allow more on its own.
+
+## Limitations
+
+- Apple Silicon only; the helper is built for arm64e.
+- Only existing conversations. Start a chat in Messages first; starting new ones isn't supported yet.
+- The helper can also send attachments, edit, unsend and manage groups, but the Python API doesn't wrap those yet.
+- Messages restarts, hidden, whenever imbridge loads the helper, which closes its windows.
+- Streams check `chat.db` every half second (see `poll_interval`), so new messages can take up to that long to arrive.
+- SMS goes through your iPhone, so Text Message Forwarding must be on.
+- The helper uses private Apple APIs, which a macOS update can change. `imbridge doctor` checks them before loading
+  the helper.
+
+## Troubleshooting
+
+- Run **`imbridge doctor`** first. Before anything is loaded, it checks SIP, the boot-arg, library validation, Full
+  Disk Access, and that every private API the helper calls still exists on your macOS. That last check matters after
+  macOS updates: a helper that calls something Apple removed would crash Messages on launch.
+- **`SendNotAllowed`:** allow the chat in your code (`IMBridge(allow=[...])`), or with `imbridge allow` in your own
+  terminal.
+- **Helper logs:** `log stream --predicate 'subsystem == "imbridge"'`
+- **Messages disappears when the helper loads.** It restarts hidden; open it from the Dock as usual.
+- **The helper won't stay loaded.** Quit BlueBubbles Server if it's installed: it relaunches Messages with its own
+  helper.
+- **`AddressNotChosen` or `WrongAddress`:** see
+  [Which of your numbers it answers on](#which-of-your-numbers-it-answers-on). `imbridge doctor` lists the numbers
+  in use.
+- **Testing in a chat with yourself.** Everything you send also comes back as received, and Messages replaces your own
+  tapback rows with the ones that come back.
+
+## Security
+
+- The helper can do anything Messages can, including send as you. It only takes requests from your Mac: imbridge
+  listens on `127.0.0.1`/`::1`, and each request must carry a token that imbridge generates (stored in
+  `~/Library/Application Support/imbridge/token`, readable only by you) and passes to Messages when it launches it.
+- Everything the other side can see is limited to allowed chats and rate-limited, as described above.
+- The bigger trade-off is SIP; see the warning above. To report a vulnerability, see
+  [SECURITY.md](https://github.com/christianblandford/imbridge/blob/main/SECURITY.md).
+
+## How the helper is built
+
+[`helper/UPSTREAM`](https://github.com/christianblandford/imbridge/blob/main/helper/UPSTREAM) pins a commit of
+BlueBubbles' helper, and [`helper/patches`](https://github.com/christianblandford/imbridge/tree/main/helper/patches)
+applies imbridge's changes in order:
+
+1. Any-emoji tapbacks, per-part text styles, and a typing-indicator crash fix
+2. Skip chat items without `-index` (the macOS 26+ crash when replying or reacting while someone is typing)
+3. A build fix for current clang
+4. imbridge's transport: its own port, the token, line-delimited requests, and fast reconnects
+
+`helper/build.sh` builds it with only the Xcode Command Line Tools. Released wheels include the built helper.
+
+## Development
+
+```bash
+git clone https://github.com/christianblandford/imbridge && cd imbridge
+python3 -m venv .venv && .venv/bin/pip install -e ".[dev]"   # also builds the helper
+.venv/bin/pytest && .venv/bin/ruff check .
+```
+
+Releases are cut by pushing a version tag; see
+[RELEASING.md](https://github.com/christianblandford/imbridge/blob/main/RELEASING.md).
+
+## Credits and license
+
+imbridge is licensed under Apache-2.0. Its helper is built from
+[BlueBubbles' Private API helper](https://github.com/BlueBubblesApp/bluebubbles-helper), also Apache-2.0; imbridge's
+any-emoji tapbacks started as a patch to it. [NOTICE](https://github.com/christianblandford/imbridge/blob/main/NOTICE)
+lists the bundled third-party code.
+
+imbridge is not affiliated with or endorsed by Apple. iMessage and Messages are trademarks of Apple Inc.