Prefer BlueBubbles for iMessage; add BlueBubbles iMessage skill

This commit is contained in:
Tyler Yust committed 2026-01-29 12:45:50 -08:00
1 parent 4583f88626
commit 79130efcb3
17 files changed
+287 -40

No files matched your search

+70 -2
View File
@@ -5,9 +5,9 @@ read_when:
- Troubleshooting webhook pairing
- Configuring iMessage on macOS
---
# BlueBubbles (macOS REST)
# iMessage (BlueBubbles)
Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended for iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel.
Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **Recommended iMessage integration** due to its richer API and easier setup compared to the legacy imsg channel.
## Overview
- Runs on macOS via the BlueBubbles helper app ([bluebubbles.app](https://bluebubbles.app)).
@@ -38,6 +38,74 @@ Status: bundled plugin that talks to the BlueBubbles macOS server over HTTP. **R
4. Point BlueBubbles webhooks to your gateway (example: `https://your-gateway-host:3000/bluebubbles-webhook?password=<password>`).
5. Start the gateway; it will register the webhook handler and start pairing.
## Keep BlueBubbles running (recommended)
If the BlueBubbles Server app quits or the Mac sleeps, iMessage delivery, webhooks, and advanced actions will stop.
### Prevent sleep
On macOS (especially VMs), ensure the machine stays awake:
- One-time: `caffeinate -dims`
- Permanent: configure your VM/host power settings (or a LaunchAgent that runs `caffeinate`).
### launchd keepalive (re-open BlueBubbles every 5 minutes)
This LaunchAgent periodically re-opens BlueBubbles + Messages in the background.
1) Create a script at `~/.clawdbot/scripts/keepalive-bluebubbles.sh`:
```bash
#!/usr/bin/env bash
set -euo pipefail
# App names vary across builds; try both.
open -gj -a "BlueBubbles" || open -gj -a "BlueBubbles Server" || true
open -gj -a "Messages" || true
```
2) Make it executable:
```bash
chmod +x ~/.clawdbot/scripts/keepalive-bluebubbles.sh
```
3) Create a LaunchAgent at `~/Library/LaunchAgents/com.moltbot.bluebubbles.keepalive.plist`:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.moltbot.bluebubbles.keepalive</string>
<key>ProgramArguments</key>
<array>
<string>/bin/bash</string>
<string>-lc</string>
<string>~/.clawdbot/scripts/keepalive-bluebubbles.sh</string>
</array>
<key>RunAtLoad</key>
<true/>
<!-- IMPORTANT: 300 seconds (5 minutes), not 600 -->
<key>StartInterval</key>
<integer>300</integer>
<key>StandardOutPath</key>
<string>/tmp/com.moltbot.bluebubbles.keepalive.out</string>
<key>StandardErrorPath</key>
<string>/tmp/com.moltbot.bluebubbles.keepalive.err</string>
</dict>
</plist>
```
4) Load it:
```bash
launchctl load -w ~/Library/LaunchAgents/com.moltbot.bluebubbles.keepalive.plist
launchctl list | rg bluebubbles
```
## Onboarding
BlueBubbles is available in the interactive setup wizard:
```
+3 -2
View File
@@ -1,11 +1,12 @@
---
summary: "iMessage support via imsg (JSON-RPC over stdio), setup, and chat_id routing"
summary: "Legacy iMessage support via imsg (JSON-RPC over stdio). Deprecated for new setups; prefer BlueBubbles."
read_when:
- Setting up iMessage support
- Debugging iMessage send/receive
---
# iMessage (imsg)
# iMessage (legacy: imsg)
> **Deprecated for new setups.** Prefer **[iMessage (BlueBubbles)](/channels/bluebubbles)**.
Status: external CLI integration. Gateway spawns `imsg rpc` (JSON-RPC over stdio).
+2 -2
View File
@@ -18,8 +18,8 @@ Text is supported everywhere; media and reactions vary by channel.
- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately).
- [Signal](/channels/signal) — signal-cli; privacy-focused.
- [BlueBubbles](/channels/bluebubbles) — **Recommended for iMessage**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
- [iMessage](/channels/imessage) — macOS only; native integration via imsg (legacy, consider BlueBubbles for new setups).
- [iMessage (BlueBubbles)](/channels/bluebubbles) — **Recommended**; uses the BlueBubbles macOS server REST API with full feature support (edit, unsend, effects, reactions, group management — edit currently broken on macOS 26 Tahoe).
- [iMessage (legacy: imsg)](/channels/imessage) — macOS only; native integration via imsg (deprecated for new setups).
- [Microsoft Teams](/channels/msteams) — Bot Framework; enterprise support (plugin, installed separately).
- [LINE](/channels/line) — LINE Messaging API bot (plugin, installed separately).
- [Nextcloud Talk](/channels/nextcloud-talk) — Self-hosted chat via Nextcloud Talk (plugin, installed separately).
+3 -1
View File
@@ -1313,7 +1313,9 @@ Reaction notification modes:
- `all`: all reactions on all messages.
- `allowlist`: reactions from `channels.signal.reactionAllowlist` on all messages (empty list disables).
### `channels.imessage` (imsg CLI)
### `channels.imessage` (legacy: imsg CLI)
**Deprecated for new setups.** Prefer **iMessage (BlueBubbles)**: [/channels/bluebubbles](/channels/bluebubbles).
Moltbot spawns `imsg rpc` (JSON-RPC over stdio). No daemon or port required.
+3 -2
View File
@@ -24,7 +24,7 @@ read_when:
<a href="/start/clawd">Moltbot assistant setup</a>
</p>
Moltbot bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (imsg CLI) to coding agents like [Pi](https://github.com/badlogic/pi-mono). Plugins add Mattermost (Bot API + WebSocket) and more.
Moltbot bridges WhatsApp (via WhatsApp Web / Baileys), Telegram (Bot API / grammY), Discord (Bot API / channels.discord.js), and iMessage (BlueBubbles recommended; imsg legacy) to coding agents like [Pi](https://github.com/badlogic/pi-mono). Plugins add Mattermost (Bot API + WebSocket) and more.
Moltbot also powers [Clawd](https://clawd.me), the space‑lobster assistant.
## Start here
@@ -81,7 +81,8 @@ Most operations flow through the **Gateway** (`moltbot gateway`), a single long-
- ✈️ **Telegram Bot** — DMs + groups via grammY
- 🎮 **Discord Bot** — DMs + guild channels via channels.discord.js
- 🧩 **Mattermost Bot (plugin)** — Bot token + WebSocket events
- 💬 **iMessage** — Local imsg CLI integration (macOS)
- 💬 **iMessage** — BlueBubbles macOS server integration (recommended)
- 💬 **iMessage (legacy)** — Local imsg CLI integration (macOS)
- 🤖 **Agent bridge** — Pi (RPC mode) with tool streaming
- ⏱️ **Streaming + chunking** — Block streaming + Telegram draft streaming details ([/concepts/streaming](/concepts/streaming))
- 🧠 **Multi-agent routing** — Route provider accounts/peers to isolated agents (workspace + per-agent sessions)
+2 -1
View File
@@ -89,7 +89,8 @@ git commit -m "Add Clawd workspace"
- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
- **oracle** — OpenAI-ready agent CLI with session replay and browser control.
- **eightctl** — Control your sleep, from the terminal.
- **imsg** — Send, read, stream iMessage & SMS.
- **imessage-bluebubbles** — iMessage via BlueBubbles (recommended): history/search/send/attachments.
- **imsg** — (legacy) Send, read, stream iMessage & SMS via imsg CLI.
- **wacli** — WhatsApp CLI: sync, search, send.
- **discord** — Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+7 -3
View File
@@ -11,9 +11,13 @@ It does not define which tools exist; Moltbot provides built-in tools internally
## Examples
### imsg
- Send an iMessage/SMS: describe who/what, confirm before sending.
- Prefer short messages; avoid sending secrets.
### iMessage (BlueBubbles)
- Preferred iMessage integration. Confirm before sending.
- If you need history/search: use the BlueBubbles REST API (chat/query, message/query).
### imsg (legacy)
- Legacy iMessage/SMS integration on macOS. Deprecated for new setups.
- Confirm before sending; avoid sending secrets.
### sag
- Text-to-speech: specify voice, target speaker/room, and whether to stream.
+1 -1
View File
@@ -123,7 +123,7 @@ Tip: `--json` does **not** imply non-interactive mode. Use `--non-interactive` (
- Google Chat: service account JSON + webhook audience.
- Mattermost (plugin): bot token + base URL.
- Signal: optional `signal-cli` install + account config.
- iMessage: local `imsg` CLI path + DB access.
- iMessage: BlueBubbles server URL + password (recommended) or legacy local `imsg` CLI path + DB access.
- DM security: default is pairing. First DM sends a code; approve via `moltbot pairing approve <channel> <code>` or use allowlists.
6) **Daemon install**