coderClaw

BlueBubbles (macOS REST)

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.

Overview

Quick start

  1. Install the BlueBubbles server on your Mac (follow the instructions at bluebubbles.app/install).
  2. In the BlueBubbles config, enable the web API and set a password.

  3. Run coderclaw onboard and select BlueBubbles, or configure manually:

    {
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}
  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.

Security note:

Keeping Messages.app alive (VM / headless setups)

Some macOS VM / always-on setups can end up with Messages.app going “idle” (incoming events stop until the app is opened/foregrounded). A simple workaround is to poke Messages every 5 minutes using an AppleScript + LaunchAgent.

1) Save the AppleScript

Save this as:

Example script (non-interactive; does not steal focus):

try
  tell application "Messages"
    if not running then
      launch
    end if

    -- Touch the scripting interface to keep the process responsive.
    set _chatCount to (count of chats)
  end tell
on error
  -- Ignore transient failures (first-run prompts, locked session, etc).
end try

2) Install a LaunchAgent

Save this as:

<?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.user.poke-messages</string>

    <key>ProgramArguments</key>
    <array>
      <string>/bin/bash</string>
      <string>-lc</string>
      <string>/usr/bin/osascript &quot;$HOME/Scripts/poke-messages.scpt&quot;</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>StartInterval</key>
    <integer>300</integer>

    <key>StandardOutPath</key>
    <string>/tmp/poke-messages.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/poke-messages.err</string>
  </dict>
</plist>

Notes:

Load it:

launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true
launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist

Onboarding

BlueBubbles is available in the interactive setup wizard:

coderclaw onboard

The wizard prompts for:

You can also add BlueBubbles via CLI:

coderclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --password <password>

Access control (DMs + groups)

DMs:

Groups:

Mention gating (groups)

BlueBubbles supports mention gating for group chats, matching iMessage/WhatsApp behavior:

Per-group configuration:

{
  channels: {
    bluebubbles: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true }, // default for all groups
        "iMessage;-;chat123": { requireMention: false }, // override for specific group
      },
    },
  },
}

Command gating

Typing + read receipts

{
  channels: {
    bluebubbles: {
      sendReadReceipts: false, // disable read receipts
    },
  },
}

Advanced actions

BlueBubbles supports advanced message actions when enabled in config:

{
  channels: {
    bluebubbles: {
      actions: {
        reactions: true, // tapbacks (default: true)
        edit: true, // edit sent messages (macOS 13+, broken on macOS 26 Tahoe)
        unsend: true, // unsend messages (macOS 13+)
        reply: true, // reply threading by message GUID
        sendWithEffect: true, // message effects (slam, loud, etc.)
        renameGroup: true, // rename group chats
        setGroupIcon: true, // set group chat icon/photo (flaky on macOS 26 Tahoe)
        addParticipant: true, // add participants to groups
        removeParticipant: true, // remove participants from groups
        leaveGroup: true, // leave group chats
        sendAttachment: true, // send attachments/media
      },
    },
  },
}

Available actions:

Message IDs (short vs full)

CoderClaw may surface short message IDs (e.g., 1, 2) to save tokens.

Use full IDs for durable automations and storage:

See Configuration for template variables.

Block streaming

Control whether responses are sent as a single message or streamed in blocks:

{
  channels: {
    bluebubbles: {
      blockStreaming: true, // enable block streaming (off by default)
    },
  },
}

Media + limits

Configuration reference

Full configuration: Configuration

Provider options:

Related global options:

Addressing / delivery targets

Prefer chat_guid for stable routing:

Security

Troubleshooting

For general channel workflow reference, see Channels and the Plugins guide.

This site is open source. Improve this page.