Introduction

DeepSeek Harness (DSH) provides plugin-based extensibility. dsh-bluebubbles is a Bridge plugin used to connect a locally running BlueBubbles service (iMessage bridging on macOS) to DSH. It routes messages to bound workspaces through REST tools and Webhook push delivery.

Core Features

This plugin mainly addresses communication between a local iMessage proxy and DSH workspaces, including the following capabilities:

  • Local Server Bridging: Connects a local BlueBubbles server to DSH.
  • REST Tools: Provides two frequently used tools: bluebubbles_send_text (send text) and bluebubbles_send_attachment (send attachment).
  • Webhook Pushes: Supports receiving pushes at the /bluebubbles/webhook path and automatically looks up the bound workspace.
  • CLI Management: Uses the bb-channel CLI for binding resolution, contact management, and configuration.
  • Helper Modules: Includes the dsh-heartbeat (heartbeat) and dsh-cron (scheduled tasks) modules.
  • Conversation Persistence: Supports cold start and session recovery.
  • API Detection: Automatically detects old and new Shell/Persistence APIs.

Typical Usage

Operations are mainly performed through the bb-channel CLI. All output is formatted JSON (jq-friendly), and error messages are written to stderr.

Chats and Messages

bb-channel chats [--limit N] [--all]
bb-channel messages <chatGuid> [--limit N]
bb-channel send <chatGuid> <text...>
bb-channel send-attachment <chatGuid> <file>

Bindings and Session Management

bb-channel bind <chatGuid> (--workspace PATH | --session ID)
bb-channel unbind <chatGuid>
bb-channel bindings

Contacts and Webhook

bb-channel contacts
bb-channel set-contact <address> <name>
bb-channel webhook [--url URL]

Environment Configuration

The timezone setting can be overridden with the environment variable BLUEBUBBLES_TZ=Asia/Shanghai.

Notes

  • Version Compatibility: Only DSH host versions 0.1.1-rc.1, 0.1.1-rc.2, and 0.1.7-rc.2 are supported. 0.1.5 and other untested preview releases are not supported.
  • Credential Chain: The environment variable read priority is process.env -> ~/.dsh/.env -> ~/.zshenv.
  • Real-Time Effect: The bb-channel CLI edits the configuration file directly, so changes take effect immediately without reloading.
  • Loop Prevention: Uses the pendingSent queue and seenGuids to prevent duplicate message sending.
  • Quote Replies: Supports iMessage quote replies (swipe-reply).

Installation and Activation

No specific installation commands are provided in the source data.

Conclusion

dsh-bluebubbles encapsulates local iMessage capabilities as REST tools and Webhooks for use by DSH Agent. Developers can directly manage chats, bindings, and contacts through the CLI, making it suitable for scenarios that require automated iMessage interaction in local environments.