Skip to content
Skills Library
Personal productivity · Tool integration

bluebubbles

/bluebubbles

Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".

Repository
brigade ↗
Licence
MIT
Last repository change
15.09.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.09.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".

Triggers from the description

bluebubbles
Original author description

Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".

How it works

  1. Overview
  2. Inputs to collect
  3. Actions
  4. Notes
  5. Ideas to try
Original SKILL.md headings · 132 lines, 461 words
SKILL.md preview
---
name: bluebubbles
description: Use when you need to send or manage iMessages via BlueBubbles (recommended iMessage integration). Calls go through the generic message tool with channel="bluebubbles".
metadata: { "brigade": { "emoji": "🫧", "requires": { "config": ["channels.bluebubbles"] } } }
---

# BlueBubbles Actions

## Overview

BlueBubbles is Brigade’s recommended iMessage integration. Use the `message` tool with `channel: "bluebubbles"` to send messages and manage iMessage conversations: send texts and attachments, react (tapbacks), edit/unsend, reply in threads, and manage group participants/names/icons.

## Inputs to collect

- `target` (prefer `chat_guid:...`; also `+15551234567` in E.164 or `user@example.com`)
- `message` text for send/edit/reply
- `messageId` for react/edit/unsend/reply
- Attachment `path` for local files, or `buffer` + `filename` for base64

If the user is vague ("text my mom"), ask for the recipient handle or chat guid and the exact message content.

## Actions

### Send a message

```json
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "hello from Brigade"
}
```

### React (tapback)

```json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️"
}
```

### Remove a reaction

```json
{
  "action": "react",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "emoji": "❤️",
  "remove": true
}
```

### Edit a previously sent message

```json
{
  "action": "edit",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>",
  "message": "updated text"
}
```

### Unsend a message

```json
{
  "action": "unsend",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "messageId": "<message-guid>"
}
```

### Reply to a specific message

```json
{
  "action": "reply",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "replyTo": "<message-guid>",
  "message": "replying to that"
}
```

### Send an attachment

```json
{
  "action": "send",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "path": "/tmp/photo.jpg",
  "message": "here you go"
}
```

Use `message` for the user-facing text. Do not rely on `caption` as a distinct BlueBubbles/iMessage feature.

### Send with an iMessage effect

```json
{
  "action": "sendWithEffect",
  "channel": "bluebubbles",
  "target": "+15551234567",
  "message": "big news",
  "effect": "balloons"
}
```

## Notes

- Requires gateway config `channels.bluebubbles` (serverUrl/password/webhookPath).
- Prefer `chat_guid` targets when you have them (especially for group chats).
- For media + text, treat `message` as canonical. Brigade can accept `caption` as an alias, but BlueBubbles/iMessage does not offer a reliable native attachment-caption concept.
- In practice, media with text may arrive as the attachment plus a separate text message rather than one captioned bubble. Do not promise exact attachment-caption rendering.
- If you must use the channel-specific file action, the canonical action name is `upload-file`; `sendAttachment` is a legacy alias.
- BlueBubbles supports rich actions, but some are macOS-version dependent (for example, edit may be broken on macOS 26 Tahoe).
- The gateway may expose both short and full message ids; full ids are more durable across restarts.
- Developer reference for the underlying plugin lives in the BlueBubbles plugin package README.

## Ideas to try

- React with a tapback to acknowledge a request.
- Reply in-thread when a user references a specific message.
- Send a file attachment with short message text, expecting BlueBubbles to treat the text as best-effort companion text rather than a guaranteed native caption.

Versions

RepositoryScoreLicence
This page · spinabot/brigade100MIT
trpc-group/trpc-agent-go100Apache-2.0
bitterbot-ai/bitterbot-desktop100MIT
the-open-agent/openagent100Apache-2.0
moltis-org/moltis100MIT
grtninja/skill-arbiter100MIT
argentaios/argentos-core100MIT

Database snapshot: 13.11.2026 · package version d5dcbaf994b6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86imessage
    Send and receive iMessages via Linq. Use when the user asks to text someone, send an iMessage, or check their messages.
  • 100imessage
    Read, send, or react to iMessage chats with the imsg tool, or stream new ones, with a read-back and a yes-gate before every send. Use when the person says text someone, check my messages, read that thread, send this file by iMessage, or react to that message. Mac-only. imsg is an Add-on.
  • 100imessage
    Read and send iMessages via local macOS capabilities (no third-party API). Two modes. Send mode drafts a message and uses AppleScript (`osascript`) on explicit "send it" and requires only Automation, Messages permission (scoped, revocable). Read mode pulls from…
  • 91photon-imessage-setup
    Use when setting up Photon iMessage on Hermes.
  • 90export-messages
    Export the user's iMessage conversations from the Messages app to Markdown, one file per conversation with attachments, using the Exporter Mac app and its exporter command line. Use when asked to export, save, archive or back up iMessages, text conversations or Messages chat…
  • 100automating-messages
    Automates macOS Messages (iMessage/SMS) via JXA with reliable service→buddy resolution. Use when asked to "automate iMessage", "send Messages via script", "JXA Messages automation", or "read Messages history". Covers send-bug workarounds, UI scripting for attachments, chat.db…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.