Self-hosted relay for macOS
iMessage to Telegram, one bot for each chat that matters.
bluehop forwards the iMessage 1:1 chats you choose to Telegram, each to its own bot chat, and sends your Telegram replies back. Link one chat or several; one process relays them all. A tiny relay for your Mac: one Swift binary you build and sign on that Mac, zero dependencies, no web UI, no open ports, and System Integrity Protection stays on.
No bluehop-operated server. Runs on your Mac; relayed bot messages are stored by Telegram and are not end-to-end encrypted.
- macOS 14+
- Swift · 0 deps
- no open ports
- no bluehop server
- SIP stays on
- MIT
Why
Some conversations only exist in iMessage: an AI assistant you can reach only over iMessage, or one family member. If the rest of your day, and your other agents, live in Telegram, bluehop lets you read and answer those conversations there. iMessage needs a Mac signed in to Messages, so the relay runs on your Mac, not on someone's server.
What it does
- iMessage → Telegram: text, replies, tapbacks as reactions, photos, voice, video, files.
- Telegram → iMessage: text, photos, voice, video, files up to 20 MB.
- Confirms each send in the Messages database; only failures get a ⚠️.
- Mirrors what you send from your iPhone so the thread stays complete.
- Several chats side by side, one Telegram bot each, isolated from each other.
What it does not do
- Group chats, or every chat through a single bot.
- A web UI, an open port, or a bluehop-run server.
- Ask you to disable SIP or use private Apple APIs.
- Real threaded replies or tapbacks into iMessage (sent as quoted text).
How it works
Everything happens on your Mac. The only host it talks to is api.telegram.org.
One binary, built on your Mac
You build and sign it locally with Xcode; a LaunchAgent runs it. Only that binary gets Full Disk Access and Automation permission; your terminal never does.
Reads your chosen chats
New rows of the linked 1:1 chats are read from
chat.db, opened read-only. Each chat has its own worker.Posts to its bot
Each chat's messages arrive in its own private bot chat. Only your Telegram user id is accepted back.
Sends and checks
Replies go out through a fixed AppleScript, then each send is confirmed in
chat.db. Nothing is resent automatically.
iMessage contact ── Messages.app on your Mac ──┐
│ chat.db (read-only)
bluehop ──── https://api.telegram.org ──── one Telegram bot chat per linked chat
│ AppleScript send
└── Messages.app → the same contact
Compared with other tools
All four run on a Mac signed in to Messages and read chat.db. bluehop trades breadth for the smallest possible attack surface.
| bluehop | chatwire | BlueBubbles | mautrix-imessage | |
|---|---|---|---|---|
| Used from | One Telegram bot chat per linked chat | Web UI, Telegram plugin, push, plugins | Android, Windows, Linux, web apps | Matrix clients |
| Chats | Chosen 1:1 chats, one bot each | All, incl. groups | All, incl. groups | All, incl. groups |
| Listens on a port | No | Yes (web UI; no auth by default, optional shared password, README) | Yes (server, via proxy or port forwarding) | Normal-Mac connector needs a Matrix homeserver and websocket proxy (setup); with a Beeper account, bbctl self-hosts it without one (docs) |
| Real replies/tapbacks into iMessage | No (quoted text) | See its docs | With its Private API; SIP off only for Private API features (docs) | Not on the normal-Mac connector; yes on the Mac-without-SIP or BlueBubbles connector (docs) |
| Stack, license | Swift, 0 deps, MIT | Python, MIT | TypeScript, Apache-2.0 | Go, AGPL-3.0 |
Sources: each project's README or official docs (linked in the cells), checked 2026-10-15. Choose a full bridge if you want every conversation or a rich client.
Install
About fifteen minutes on a Mac that stays on, once full Xcode is installed (several GB; needed to build and test), ideally with an Apple Development or Developer ID signing certificate (without one, macOS asks for the permissions again after every reinstall). There is no prebuilt download yet. Every step has a check in the agent guide, so a coding agent can drive it; a person grants Full Disk Access and the Messages Automation prompt, and creates the bot token.
git clone https://github.com/kanziw/bluehop
cd bluehop
bash scripts/install.sh --no-load
# grant Full Disk Access to the binary, then:
"$HOME/Library/Application Support/bluehop/bin/bluehop" mapping add
bash scripts/agent-run.sh doctor --messages --telegram
bash scripts/install.sh # starts the relay: real relaying from here- Create a bot with @BotFather, one per chat you want to link.
- Build and install with the script; nothing starts yet.
- Grant Full Disk Access to the binary only, then run
bluehop mapping add: paste the token, pick the chat with the arrow keys, message the bot once. - Run
doctor; when every line is ✔, start the LaunchAgent.
Needs full Xcode (Swift 6) to build. Exact commands and checks: agent guide; which commands change state: its side-effect table.
FAQ
Can I get iMessages in Telegram?
Yes, for the 1:1 conversations you choose. bluehop runs on a Mac signed in to Messages, reads new messages of each linked chat from the Messages database (read-only), and forwards them to that chat's Telegram bot. Replies you write in Telegram are sent back to the same chat.
Do I need to disable SIP?
No. bluehop uses only public mechanisms: read-only access to chat.db and AppleScript to send. The trade-off: replies and reactions you make in Telegram cannot become real iMessage threaded replies or tapbacks. Replies are sent with a quoted prefix; reactions are ignored by default.
Can I relay several chats?
Yes, since 0.5.0. Each linked iMessage 1:1 chat gets its own Telegram bot (create one per chat with @BotFather), and one bluehop process relays them all. Add one with bluehop mapping add: it asks for the bot token, lets you pick the chat with the arrow keys and detects your Telegram ids from one message to the bot. Chats are isolated: a revoked token or a safety halt in one does not stop the others, and the same chat or bot cannot be linked twice. bluehop status shows each one.
Does it work with group chats?
No. Only 1:1 chats can be linked; a group chat is refused.
Does it open a port or use a server?
There is no bluehop-operated server, no web UI and no listening socket. bluehop runs on your Mac and makes outbound HTTPS requests to api.telegram.org only. Relayed bot messages are stored by Telegram and are not end-to-end encrypted.
Do I need a Mac?
Yes. iMessage requires a Mac signed in to Messages. bluehop runs there as a LaunchAgent; it is not a hosted service.
Can an AI agent install it for me?
Mostly. The agent guide lists every step with a check, every command has --help and --json, and the repository ships an agent skill file. A person still has to grant Full Disk Access and Automation, and hand over the bot token (on stdin, never in chat), because macOS and good security require it.
Is the bot in English?
Not yet. Bot replies and logs are in Korean. doctor, mapping test and status print English with --lang en, and their --json output has stable error codes for agents. Your relayed messages pass through unchanged.