rousseau imessage

Overview

rousseau imessage runs the iMessage bridge by polling a locally installed BlueBubbles server. BlueBubbles is a macOS-only helper that exposes iMessage over an HTTP + WebSocket API. Rousseau does not send iMessages directly (Apple does not offer a public API) — it goes through BlueBubbles.

Source: internal/cli/imessage.go. Transport: internal/transport/imessage/.

Synopsis

rousseau imessage [--base-url http://host:port] [--password <pw>] [--poll-interval 5s]

Flags

Config keys respected

internal/config/config.go IMessageConfig:

Key	Type	Default	Effect
imessage.base_url	string	empty	Required.
imessage.password	string	empty	Required.
imessage.chat_guid	string	empty	Outbound target chat GUID (optional).
imessage.poll_interval	duration	5s	Poll cadence.
imessage.reply_header	string	empty	Prefix on outbound messages.

Allowlist syntax

iMessage has no --allow flag today. Filtering must happen at the BlueBubbles server side (its own contact allowlist), or use the chat_guid config to constrain outbound to a single conversation.

Environment variables

Variable	Effect
ROUSSEAU_IMESSAGE_BASE_URL	Override BlueBubbles URL.
ROUSSEAU_IMESSAGE_PASSWORD	Override BlueBubbles password.

Startup sequence

1. Resolve URL and password; fail if either is empty.
2. Default claudecli.permission_mode to bypassPermissions.
3. Parse poll_interval.
4. Open session store, build agent wiring.
5. imessage.New — instantiate the HTTP client.
6. wiring.startCron — cron delivery via BlueBubbles POST.
7. Poll loop until context cancelled.

Exit codes

Code	Meaning
0	Clean context cancellation.
1	Missing URL/password, HTTP failure, provider/store error.
130	SIGINT.

Worked examples

# Local BlueBubbles on the same Mac
rousseau imessage \
  --base-url http://localhost:1234 \
  --password "$BLUEBUBBLES_PW"

# Remote Mac via SSH tunnel
ssh -N -L 1234:localhost:1234 mac.internal &
rousseau imessage \
  --base-url http://localhost:1234 \
  --password "$BLUEBUBBLES_PW" \
  --poll-interval 3s

Common failure modes

• 401 Unauthorized — wrong password.
• Connection refused — BlueBubbles server not running or wrong port.
• No inbound messages — verify the BlueBubbles UI shows recent conversations; enable Full Disk Access in macOS for BlueBubbles.
• Delayed replies — reduce poll_interval; the default 5s is a compromise between latency and CPU.

Related pages

• Transports: iMessage
• Best Practices: Secret management
• Reference: Logs