mac-imsg 0.1.0__tar.gz

mac_imsg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ml-lubich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mac_imsg-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: mac-imsg
+Version: 0.1.0
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: License :: OSI Approved :: MIT License
+Requires-Dist: typer>=0.12
+Requires-Dist: rich>=13.7
+Requires-Dist: mcp[cli]>=1.6.0
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Provides-Extra: dev
+License-File: LICENSE
+Summary: Fast, local iMessage for your terminal + MCP — Rust-accelerated read/search, AppleScript send. macOS only.
+Keywords: imessage,macos,mcp,cli,rust,applescript
+Author: ml-lubich
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Homepage, https://github.com/ml-lubich/imsg
+Project-URL: Repository, https://github.com/ml-lubich/imsg
+
+# imsg — fast, local iMessage for your terminal & MCP
+
+[![PyPI](https://img.shields.io/pypi/v/imsg.svg)](https://pypi.org/project/imsg/)
+[![Python](https://img.shields.io/pypi/pyversions/imsg.svg)](https://pypi.org/project/imsg/)
+[![Built with Rust](https://img.shields.io/badge/core-Rust-orange.svg)](rust/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![macOS only](https://img.shields.io/badge/os-macOS-black.svg)](#requirements)
+
+Read, search, and send iMessage from your terminal — or expose it to Claude,
+Cursor, VS Code, or any MCP client. Everything runs **locally on your Mac**:
+no cloud, no login, no account. Reads open `~/Library/Messages/chat.db`
+**read-only**; sends go through Messages.app.
+
+**Why another one?** The hot path — decoding tens of thousands of
+`attributedBody` typedstream blobs — is written in **Rust** (PyO3 + rusqlite),
+so reads and searches over a large history are several times faster than the
+pure-Python equivalent that other Messages servers use. Pure Python still ships
+as a zero-dependency fallback, so it works even where the wheel doesn't.
+
+<!-- BENCH -->
+### Benchmark
+
+Full-history search over a synthetic **50,000-message** database (70% stored as
+`attributedBody` blobs), best-of-5, Apple Silicon (16 cores):
+
+| operation | pure-Python | Rust core | speedup |
+|---|---:|---:|---:|
+| **full-history search** (decodes every message) | 120.9 ms | **35.7 ms** | **3.4×** |
+| batched blob decode (allocation-bound) | 19.1 ms | 19.6 ms | 1.0× |
+
+Two honest caveats, stated up front:
+- Raw blob decoding is ~a wash — it's bound by allocating result strings, not
+  CPU, so native code doesn't help. The win is in **search**, where Rust
+  decodes and filters across all cores and returns only the matches.
+- It's 3.4×, not 16×, because the SQLite read and result marshalling are serial
+  on both sides; only the decode+match parallelizes. The gap widens on larger
+  histories.
+
+Reproduce: `python bench/benchmark.py`. **Bonus:** this search also finds
+messages whose text lives in an `attributedBody` blob — which a plain
+`text LIKE` query (used by Python-only Messages servers) silently misses.
+<!-- /BENCH -->
+
+## Install
+
+```bash
+# with uv (recommended) — provisions Python + the prebuilt wheel
+uv tool install imsg
+
+# or pip
+pip install imsg
+
+# or Homebrew
+brew install ml-lubich/tap/imsg
+```
+
+## Requirements
+
+- **macOS** (reads the local Messages database; sends via Messages.app).
+- **Full Disk Access** for the app that runs `imsg` — Terminal/iTerm/Ghostty
+  for the CLI, or your MCP client (Claude Desktop, Cursor, VS Code…) for the
+  server. System Settings → Privacy & Security → Full Disk Access → add it,
+  then fully quit and reopen it.
+- Messages.app signed in and able to send a normal message.
+
+Run `imsg doctor` to check access and see which engine (Rust or Python) is live.
+
+## CLI
+
+```bash
+imsg doctor                       # check Full Disk Access + engine
+imsg chats                        # recent conversations + their ids
+imsg contacts                     # handles (numbers / emails) seen
+imsg read -c +14155551234         # recent messages with a contact
+imsg read --chat 42 --limit 100   # a specific conversation
+imsg search "dinner"              # search message text
+imsg send +14155551234 "on my way"
+```
+
+## MCP server
+
+The `imsg-mcp` entry point speaks MCP over stdio. Add it to any client:
+
+**Claude Code**
+```bash
+claude mcp add --transport stdio --scope user imsg -- imsg-mcp
+```
+
+**Claude Desktop / Cursor** (`mcpServers`) · **VS Code** (`servers`):
+```json
+{ "mcpServers": { "imsg": { "command": "imsg-mcp" } } }
+```
+
+Tools exposed: `check_access`, `get_recent_messages`, `search_messages`,
+`list_chats`, `list_contacts`, `send_message` (the only one with a side effect).
+
+## How it works
+
+There is no official iMessage API. Every tool in this space does the same two
+local things; `imsg` just does the heavy half in Rust:
+
+| Operation | Mechanism | Engine |
+|---|---|---|
+| read / search / list | `chat.db` (SQLite, read-only) + typedstream decode | **Rust** (`imsgcore`), Python fallback |
+| send | AppleScript → Messages.app | Python (`osascript`) |
+
+SQLite is the same C library everywhere, so the read speedup comes from doing
+the per-message `attributedBody` decode and row marshalling natively instead of
+in a Python loop. See [`bench/benchmark.py`](bench/benchmark.py) for the
+methodology — both engines run identical queries over an identical synthetic
+database, and the pure-Python column is the same algorithm Python-only servers
+use.
+
+## Privacy & security
+
+- All database connections are opened **read-only** (`mode=ro`).
+- Nothing is uploaded, mirrored, or indexed off-device.
+- Sending is isolated in one function, escapes its AppleScript inputs, and is
+  the only operation that writes anything anywhere.
+- Full Disk Access is broad — grant it only to apps you trust.
+
+## Development
+
+```bash
+git clone https://github.com/ml-lubich/imsg.git && cd imsg
+uv venv && source .venv/bin/activate
+uv pip install maturin
+maturin develop            # builds the Rust core + installs the package
+uv pip install -e ".[dev]"
+pytest                     # tests run on the pure-Python path (and Rust if built)
+python bench/benchmark.py  # regenerate the benchmark
+```
+
+## License
+
+MIT © ml-lubich. Not affiliated with Apple. Use responsibly and only with
+accounts and conversations you own.
+

mac_imsg-0.1.0/README.md

@@ -0,0 +1,137 @@
+# imsg — fast, local iMessage for your terminal & MCP
+
+[![PyPI](https://img.shields.io/pypi/v/imsg.svg)](https://pypi.org/project/imsg/)
+[![Python](https://img.shields.io/pypi/pyversions/imsg.svg)](https://pypi.org/project/imsg/)
+[![Built with Rust](https://img.shields.io/badge/core-Rust-orange.svg)](rust/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![macOS only](https://img.shields.io/badge/os-macOS-black.svg)](#requirements)
+
+Read, search, and send iMessage from your terminal — or expose it to Claude,
+Cursor, VS Code, or any MCP client. Everything runs **locally on your Mac**:
+no cloud, no login, no account. Reads open `~/Library/Messages/chat.db`
+**read-only**; sends go through Messages.app.
+
+**Why another one?** The hot path — decoding tens of thousands of
+`attributedBody` typedstream blobs — is written in **Rust** (PyO3 + rusqlite),
+so reads and searches over a large history are several times faster than the
+pure-Python equivalent that other Messages servers use. Pure Python still ships
+as a zero-dependency fallback, so it works even where the wheel doesn't.
+
+<!-- BENCH -->
+### Benchmark
+
+Full-history search over a synthetic **50,000-message** database (70% stored as
+`attributedBody` blobs), best-of-5, Apple Silicon (16 cores):
+
+| operation | pure-Python | Rust core | speedup |
+|---|---:|---:|---:|
+| **full-history search** (decodes every message) | 120.9 ms | **35.7 ms** | **3.4×** |
+| batched blob decode (allocation-bound) | 19.1 ms | 19.6 ms | 1.0× |
+
+Two honest caveats, stated up front:
+- Raw blob decoding is ~a wash — it's bound by allocating result strings, not
+  CPU, so native code doesn't help. The win is in **search**, where Rust
+  decodes and filters across all cores and returns only the matches.
+- It's 3.4×, not 16×, because the SQLite read and result marshalling are serial
+  on both sides; only the decode+match parallelizes. The gap widens on larger
+  histories.
+
+Reproduce: `python bench/benchmark.py`. **Bonus:** this search also finds
+messages whose text lives in an `attributedBody` blob — which a plain
+`text LIKE` query (used by Python-only Messages servers) silently misses.
+<!-- /BENCH -->
+
+## Install
+
+```bash
+# with uv (recommended) — provisions Python + the prebuilt wheel
+uv tool install imsg
+
+# or pip
+pip install imsg
+
+# or Homebrew
+brew install ml-lubich/tap/imsg
+```
+
+## Requirements
+
+- **macOS** (reads the local Messages database; sends via Messages.app).
+- **Full Disk Access** for the app that runs `imsg` — Terminal/iTerm/Ghostty
+  for the CLI, or your MCP client (Claude Desktop, Cursor, VS Code…) for the
+  server. System Settings → Privacy & Security → Full Disk Access → add it,
+  then fully quit and reopen it.
+- Messages.app signed in and able to send a normal message.
+
+Run `imsg doctor` to check access and see which engine (Rust or Python) is live.
+
+## CLI
+
+```bash
+imsg doctor                       # check Full Disk Access + engine
+imsg chats                        # recent conversations + their ids
+imsg contacts                     # handles (numbers / emails) seen
+imsg read -c +14155551234         # recent messages with a contact
+imsg read --chat 42 --limit 100   # a specific conversation
+imsg search "dinner"              # search message text
+imsg send +14155551234 "on my way"
+```
+
+## MCP server
+
+The `imsg-mcp` entry point speaks MCP over stdio. Add it to any client:
+
+**Claude Code**
+```bash
+claude mcp add --transport stdio --scope user imsg -- imsg-mcp
+```
+
+**Claude Desktop / Cursor** (`mcpServers`) · **VS Code** (`servers`):
+```json
+{ "mcpServers": { "imsg": { "command": "imsg-mcp" } } }
+```
+
+Tools exposed: `check_access`, `get_recent_messages`, `search_messages`,
+`list_chats`, `list_contacts`, `send_message` (the only one with a side effect).
+
+## How it works
+
+There is no official iMessage API. Every tool in this space does the same two
+local things; `imsg` just does the heavy half in Rust:
+
+| Operation | Mechanism | Engine |
+|---|---|---|
+| read / search / list | `chat.db` (SQLite, read-only) + typedstream decode | **Rust** (`imsgcore`), Python fallback |
+| send | AppleScript → Messages.app | Python (`osascript`) |
+
+SQLite is the same C library everywhere, so the read speedup comes from doing
+the per-message `attributedBody` decode and row marshalling natively instead of
+in a Python loop. See [`bench/benchmark.py`](bench/benchmark.py) for the
+methodology — both engines run identical queries over an identical synthetic
+database, and the pure-Python column is the same algorithm Python-only servers
+use.
+
+## Privacy & security
+
+- All database connections are opened **read-only** (`mode=ro`).
+- Nothing is uploaded, mirrored, or indexed off-device.
+- Sending is isolated in one function, escapes its AppleScript inputs, and is
+  the only operation that writes anything anywhere.
+- Full Disk Access is broad — grant it only to apps you trust.
+
+## Development
+
+```bash
+git clone https://github.com/ml-lubich/imsg.git && cd imsg
+uv venv && source .venv/bin/activate
+uv pip install maturin
+maturin develop            # builds the Rust core + installs the package
+uv pip install -e ".[dev]"
+pytest                     # tests run on the pure-Python path (and Rust if built)
+python bench/benchmark.py  # regenerate the benchmark
+```
+
+## License
+
+MIT © ml-lubich. Not affiliated with Apple. Use responsibly and only with
+accounts and conversations you own.

mac_imsg-0.1.0/imessage_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""imsg: fast, local iMessage access (Rust-accelerated) with CLI + MCP server."""
+
+__version__ = "0.1.0"
+
+# True when the compiled Rust core (imsgcore) is importable; the pure-Python
+# path in imessage.py is used otherwise. Exposed so `imsg doctor` / benchmarks
+# can report which engine is active.
+try:  # pragma: no cover - presence depends on build
+    import imsgcore  # noqa: F401
+
+    HAVE_RUST = True
+except ImportError:  # pragma: no cover
+    HAVE_RUST = False

mac_imsg-0.1.0/imessage_mcp/imessage.py

@@ -0,0 +1,358 @@
+"""Core iMessage access: read the local chat.db (read-only) and send via osascript.
+
+No bridge or daemon is needed. Unlike WhatsApp (remote data behind a Go
+bridge), iMessage data already lives locally in ~/Library/Messages/chat.db and
+Messages.app can be driven with AppleScript. The CLI and the MCP server both
+call the functions here directly.
+
+Requirements at runtime:
+  - Full Disk Access for the process reading chat.db (System Settings ->
+    Privacy & Security -> Full Disk Access -> add your terminal / the app).
+  - Automation permission for Messages.app (granted on first send).
+"""
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+# Apple's Core Data epoch: 2001-01-01 UTC, in unix seconds.
+_APPLE_EPOCH = 978307200
+
+DEFAULT_DB = Path.home() / "Library" / "Messages" / "chat.db"
+
+try:  # Rust-accelerated core; falls back to pure Python when absent.
+    import imsgcore as _RUST
+except ImportError:  # pragma: no cover - depends on build
+    _RUST = None
+
+
+class AccessError(RuntimeError):
+    """chat.db exists but cannot be opened (missing Full Disk Access)."""
+
+
+def db_path() -> Path:
+    """The chat.db path, overridable via IMESSAGE_DB (handy for tests)."""
+    return Path(os.environ.get("IMESSAGE_DB", str(DEFAULT_DB)))
+
+
+def _connect(path: Path | None = None):
+    import sqlite3
+
+    p = path or db_path()
+    if not p.exists():
+        raise AccessError(f"chat.db not found at {p}")
+    try:
+        return sqlite3.connect(f"file:{p}?mode=ro", uri=True)
+    except sqlite3.OperationalError as exc:  # pragma: no cover - env specific
+        raise AccessError(
+            f"cannot open {p}: {exc}. Grant Full Disk Access to this terminal "
+            "in System Settings -> Privacy & Security -> Full Disk Access."
+        ) from exc
+
+
+def _via_rust(thunk):
+    """Run a Rust core call, translating its RuntimeError (e.g. an unopenable
+    chat.db from missing Full Disk Access) into AccessError so the CLI/MCP
+    handle it the same way as the pure-Python path."""
+    try:
+        return thunk()
+    except RuntimeError as exc:
+        raise AccessError(
+            f"cannot open {db_path()}: {exc}. Grant Full Disk Access to this "
+            "terminal in System Settings -> Privacy & Security -> Full Disk "
+            "Access, then fully quit and reopen it."
+        ) from exc
+
+
+def _apple_time_to_iso(raw: int | None) -> str | None:
+    """Convert a chat.db `date` value to an ISO-8601 UTC string.
+
+    Modern macOS stores nanoseconds since the Apple epoch; older stores
+    seconds. Disambiguate by magnitude (ns values are ~1e18).
+    """
+    if not raw:
+        return None
+    seconds = raw / 1_000_000_000 if raw > 1_000_000_000_000 else raw
+    ts = seconds + _APPLE_EPOCH
+    return datetime.fromtimestamp(ts, tz=timezone.utc).isoformat()
+
+
+def _decode_attributed_body(blob: bytes | None) -> str | None:
+    """Best-effort text extraction from a message's attributedBody blob.
+
+    Newer messages leave `text` NULL and stash the body in a typedstream
+    archive. This scans for the NSString payload and reads its length-prefixed
+    UTF-8 content — the widely-used heuristic.
+
+    ponytail: byte-scan heuristic, not a full typedstream parser. Handles the
+    common single-run case; upgrade to `pip install pytypedstream` if rich
+    multi-run attributed strings start losing text.
+    """
+    if not blob or b"NSString" not in blob:
+        return None
+    data = blob.split(b"NSString", 1)[1]
+    # Skip the class-version bytes that precede the length marker.
+    data = data[5:]
+    if not data:
+        return None
+    marker = data[0]
+    if marker == 0x81:  # 2-byte little-endian length
+        if len(data) < 3:
+            return None
+        length = int.from_bytes(data[1:3], "little")
+        start = 3
+    else:  # single-byte length
+        length = marker
+        start = 1
+    text = data[start : start + length].decode("utf-8", errors="replace")
+    return text or None
+
+
+@dataclass
+class Chat:
+    chat_id: int
+    identifier: str
+    name: str | None
+    service: str | None
+
+    def dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Message:
+    text: str | None
+    sender: str  # "me" or a handle id (phone/email)
+    is_from_me: bool
+    date: str | None
+    service: str | None
+    has_attachment: bool
+
+    def dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass
+class Contact:
+    handle: str  # phone number or email
+    service: str | None
+
+    def dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _rows(cur) -> Iterable[tuple]:
+    while True:
+        row = cur.fetchone()
+        if row is None:
+            return
+        yield row
+
+
+def list_chats(limit: int = 20, path: Path | None = None) -> list[Chat]:
+    """Recent conversations, most-recently-active first."""
+    if _RUST is not None:
+        rows = _via_rust(lambda: _RUST.list_chats(str(path or db_path()), limit))
+        return [Chat(*r) for r in rows]
+    conn = _connect(path)
+    try:
+        cur = conn.execute(
+            """
+            SELECT c.ROWID, c.chat_identifier, c.display_name, c.service_name,
+                   MAX(m.date) AS last
+            FROM chat c
+            JOIN chat_message_join cmj ON cmj.chat_id = c.ROWID
+            JOIN message m ON m.ROWID = cmj.message_id
+            GROUP BY c.ROWID
+            ORDER BY last DESC
+            LIMIT ?
+            """,
+            (limit,),
+        )
+        return [Chat(r[0], r[1], r[2], r[3]) for r in _rows(cur)]
+    finally:
+        conn.close()
+
+
+def list_contacts(limit: int = 100, path: Path | None = None) -> list[Contact]:
+    """Distinct handles (phone numbers / emails) seen in the message store."""
+    if _RUST is not None:
+        rows = _via_rust(lambda: _RUST.list_contacts(str(path or db_path()), limit))
+        return [Contact(*r) for r in rows]
+    conn = _connect(path)
+    try:
+        cur = conn.execute(
+            "SELECT DISTINCT id, service FROM handle ORDER BY id LIMIT ?",
+            (limit,),
+        )
+        return [Contact(r[0], r[1]) for r in _rows(cur)]
+    finally:
+        conn.close()
+
+
+def _message_from_rust(t: tuple) -> Message:
+    """Wrap a tuple from imsgcore into a Message.
+
+    Rust returns (text|None, is_from_me, sender, date_raw, service, has_attach)
+    with text already resolved (attributedBody decoded in Rust).
+    """
+    text, is_from_me, sender, date_raw, service, has_attach = t
+    return Message(
+        text=text,
+        sender=sender,
+        is_from_me=bool(is_from_me),
+        date=_apple_time_to_iso(date_raw),
+        service=service,
+        has_attachment=bool(has_attach),
+    )
+
+
+def _message_from_row(row: tuple) -> Message:
+    text, body, is_from_me, handle, date, service, has_attach = row
+    resolved = text or _decode_attributed_body(body)
+    return Message(
+        text=resolved,
+        sender="me" if is_from_me else (handle or "unknown"),
+        is_from_me=bool(is_from_me),
+        date=_apple_time_to_iso(date),
+        service=service,
+        has_attachment=bool(has_attach),
+    )
+
+
+_MESSAGE_COLS = (
+    "m.text, m.attributedBody, m.is_from_me, h.id, m.date, m.service, "
+    "m.cache_has_attachments"
+)
+
+
+def read_messages(
+    contact: str | None = None,
+    chat_id: int | None = None,
+    limit: int = 20,
+    path: Path | None = None,
+) -> list[Message]:
+    """Most recent messages, optionally filtered by contact handle or chat_id.
+
+    Returned oldest-first (chronological) for readable transcripts.
+    """
+    if _RUST is not None:
+        rows = _via_rust(lambda: _RUST.read_messages(str(path or db_path()), contact, chat_id, limit))
+        return list(reversed([_message_from_rust(r) for r in rows]))
+    conn = _connect(path)
+    try:
+        where = []
+        params: list[Any] = []
+        if chat_id is not None:
+            where.append(
+                "m.ROWID IN (SELECT message_id FROM chat_message_join WHERE chat_id = ?)"
+            )
+            params.append(chat_id)
+        if contact:
+            where.append("h.id = ?")
+            params.append(contact)
+        clause = ("WHERE " + " AND ".join(where)) if where else ""
+        params.append(limit)
+        cur = conn.execute(
+            f"""
+            SELECT {_MESSAGE_COLS}
+            FROM message m
+            LEFT JOIN handle h ON h.ROWID = m.handle_id
+            {clause}
+            ORDER BY m.date DESC
+            LIMIT ?
+            """,
+            params,
+        )
+        msgs = [_message_from_row(r) for r in _rows(cur)]
+        return list(reversed(msgs))
+    finally:
+        conn.close()
+
+
+def search_messages(query: str, limit: int = 20, path: Path | None = None) -> list[Message]:
+    """Full-text-ish LIKE search over message bodies, newest first."""
+    if _RUST is not None:
+        rows = _via_rust(lambda: _RUST.search_messages(str(path or db_path()), query, limit))
+        return [_message_from_rust(r) for r in rows]
+    conn = _connect(path)
+    try:
+        cur = conn.execute(
+            f"""
+            SELECT {_MESSAGE_COLS}
+            FROM message m
+            LEFT JOIN handle h ON h.ROWID = m.handle_id
+            WHERE m.text LIKE ?
+            ORDER BY m.date DESC
+            LIMIT ?
+            """,
+            (f"%{query}%", limit),
+        )
+        return [_message_from_row(r) for r in _rows(cur)]
+    finally:
+        conn.close()
+
+
+def search_all(query: str, limit: int = 100, path: Path | None = None) -> list[Message]:
+    """Search the FULL history, including messages stored as attributedBody
+    blobs that a plain `text LIKE` query silently misses.
+
+    Rust decodes and matches every message in parallel across cores; the
+    pure-Python fallback below does the same single-threaded (and is the honest
+    baseline the benchmark compares against).
+    """
+    if _RUST is not None:
+        rows = _via_rust(lambda: _RUST.search_all(str(path or db_path()), query, limit))
+        return [_message_from_rust(r) for r in rows]
+
+    needle = query.lower()
+    conn = _connect(path)
+    try:
+        cur = conn.execute(
+            f"SELECT {_MESSAGE_COLS} FROM message m "
+            "LEFT JOIN handle h ON h.ROWID = m.handle_id ORDER BY m.date DESC"
+        )
+        out: list[Message] = []
+        for row in _rows(cur):
+            msg = _message_from_row(row)
+            if msg.text and needle in msg.text.lower():
+                out.append(msg)
+                if len(out) >= limit:
+                    break
+        return out
+    finally:
+        conn.close()
+
+
+def _osascript(script: str) -> None:
+    proc = subprocess.run(
+        ["osascript", "-e", script],
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        raise RuntimeError(proc.stderr.strip() or "osascript failed")
+
+
+def send_message(recipient: str, text: str) -> None:
+    """Send an iMessage/SMS to a handle (phone number or email) via Messages.app.
+
+    Tries the iMessage service first; Messages falls back to SMS for handles
+    that aren't on iMessage when the account allows it.
+    """
+    if not recipient or not text:
+        raise ValueError("recipient and text are required")
+    safe_text = text.replace("\\", "\\\\").replace('"', '\\"')
+    safe_recip = recipient.replace("\\", "\\\\").replace('"', '\\"')
+    script = f'''
+    tell application "Messages"
+        set targetService to 1st account whose service type = iMessage
+        set targetBuddy to participant "{safe_recip}" of targetService
+        send "{safe_text}" to targetBuddy
+    end tell
+    '''
+    _osascript(script)