[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-94732":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":19,"hasPages":19,"topics":21,"createdAt":10,"pushedAt":10,"updatedAt":24,"readmeContent":25,"aiSummary":26,"trendingCount":15,"starSnapshotCount":15,"syncStatus":14,"lastSyncTime":27,"discoverSource":28},94732,"blueferry","erikwb\u002Fblueferry","erikwb","iMessage\u002FSMS over Bluetooth to Linux. No proxy or cloud!","",null,"Python",128,4,2,0,10,43.1,"Other",false,"main",[22,23],"imessage","linux","2026-08-24 04:01:22","# BlueFerry\n\n![BlueFerry messaging client](screenshot.png)\n\nUse your iPhone's messages on Linux over Bluetooth.\n\n\u003Cp align=\"center\">\n  \u003Cimg src=\"https:\u002F\u002Fupload.wikimedia.org\u002Fwikipedia\u002Fcommons\u002Fthumb\u002F9\u002F90\u002FFerry_Blue_star_1_Rhodes.jpg\u002F1920px-Ferry_Blue_star_1_Rhodes.jpg\" width=\"320\" alt=\"Blue Star ferry at Rhodes\">\n\u003C\u002Fp>\n\nBlueFerry brings SMS and iMessage from a paired iPhone to your Linux desktop.\nYou can read and reply to messages, start a conversation, search synced\ncontacts, and optionally mirror other iPhone notifications. There is no Mac\nrelay, Apple login, cloud service, or subscription.\n\nThis is still experimental software. Most development has used an iPhone 16\nPro Max on iOS 26.5, with additional successful testing on an iPhone 17 Pro Max\nrunning an iOS 27 beta. Apple can change the Bluetooth behavior BlueFerry relies\non, so don't make it your only way to receive an important message yet.\n\n## What works\n\n- Receive and send SMS and iMessage through the iPhone.\n- Sync contacts, including phone numbers and Apple-ID email addresses.\n- Mark messages read from the desktop.\n- Use native GTK, KDE\u002FKirigami, Quickshell, or terminal clients.\n- Keep local history encrypted with GNOME Keyring or KDE Wallet.\n- Reply to group chats when BlueFerry can identify the participants safely.\n\nBlueFerry only knows about messages it sees while connected; it does not\ndownload your iCloud Messages archive. Attachments, reactions, typing\nindicators, FaceTime, calls, and complete sent-message history are not\nsupported. MMS and RCS need more testing.\n\nGroup replies are deliberately cautious. Bluetooth does not give BlueFerry a\nreliable group ID or complete roster, so it disables replies when the\nparticipants are unclear. Named groups may ask you to confirm a local reply\nroster. This does not change the group on the iPhone.\n\n## Install\n\n### Arch Linux and CachyOS\n\nClone the repository and run:\n\n```bash\n.\u002Fbuild.sh -si\n```\n\nThis builds and installs four normal pacman packages: `blueferry-backend`\n(including the terminal client), `blueferry-gtk`, `blueferry-qt`, and\n`blueferry-quickshell`. It uses repository dependencies rather than downloading\nfrom the AUR or PyPI.\n\nRun `.\u002Fbuild.sh` without `-i` if you only want the package files. They are\nwritten to `packaging\u002Farch\u002F`. More details are in\n[packaging\u002Farch\u002FREADME.md](packaging\u002Farch\u002FREADME.md).\n\n### Debian, Ubuntu, Mint, Pop!_OS, PikaOS, and Fedora\n\nNative DEB and RPM recipes are included too. The tested matrix currently covers\nDebian 13, Ubuntu 24.04 and 26.04, Linux Mint 22.3, Pop!_OS 24.04, PikaOS IV,\nand Fedora 43 and 44. Some older Debian-family releases do not have the Qt\ndependencies, but the GTK client, backend, and TUI are still supported.\n\nSee [packaging\u002FREADME.md](packaging\u002FREADME.md) for the exact support matrix and\nlocal build commands.\n\nArch and Fedora packages can set up the newer Bluetooth support needed for\niPhone system notifications. Debian-family packages do not change or restart\nBluetooth; messages and contacts still work, and notifications are added only\nwhen that machine already supports them.\n\n## Pair an iPhone\n\nStart the client that fits your desktop:\n\n```bash\nblueferry-gtk         # GNOME, Cinnamon, and similar desktops\nblueferry-qt          # KDE Plasma\nblueferry-quickshell  # Quickshell\n```\n\nThen:\n\n1. Keep the iPhone unlocked with **Settings → Bluetooth** open.\n2. Let BlueFerry check your Bluetooth controller.\n3. In BlueFerry, choose **Scan**, select the iPhone, and choose **Pair**.\n   BlueFerry starts the pairing request; you do not need to find and tap the\n   computer under **Other Devices** on the phone.\n4. When the request appears on the iPhone, approve it and confirm that both\n   devices show the same code. It can take around 15 seconds to appear.\n5. After pairing, tap **ⓘ** beside the computer on the iPhone and enable\n   **Show Message Notifications** and **Sync Contacts**. If the toggles are\n   missing, return to the Bluetooth device list and reopen the **ⓘ** page a few\n   times. If iOS asks to **Allow System Notifications**, approve that too.\n6. Wait for Messages and Contacts to show as connected. If you use the default\n   encrypted storage, approve the desktop wallet prompt.\n\nSystem Notification access lets BlueFerry recognize group-message metadata.\nWhen it is unavailable, ordinary messages and contacts still work, but a group\nmessage may look like a direct conversation with its sender.\n\n### Pairing options\n\nMost people should leave both options unchecked.\n\n- **Compatibility pairing for iOS 18 or earlier** keeps the signal that makes\n  the Messages and Contacts permissions appear, but does not connect iPhone\n  system notifications. BlueFerry also chooses this automatically when the\n  local BlueZ stack cannot support them.\n- **Use explicit Bluetooth pairing** skips the normal connection-first\n  approach and asks BlueZ to pair immediately. Try it only if normal pairing\n  keeps getting canceled on that Bluetooth controller. It is independent of\n  iOS compatibility mode.\n\nFor a clean retry, forget the computer on the iPhone and forget the iPhone on\nLinux before pairing again. Stale phone-side Bluetooth state can survive a\none-sided forget, so reset both sides rather than repeatedly pairing over the\nold record.\n\nThe terminal wizard exposes the same flow:\n\n```bash\nblueferry pair-setup\nblueferry pair-setup --compatibility-mode\nblueferry pair-setup --explicit-pairing\n```\n\nOnce setup is complete, the backend starts automatically and reconnects after\nnormal Bluetooth interruptions. Package upgrades and same-version local\nrebuilds are detected automatically, so an old backend process is restarted\nwhen needed.\n\n## Terminal client\n\nThe TUI is included in `blueferry-backend` on every supported package format.\nArch uses its repository Textual package; DEB and RPM builds carry a private\nTextual 8 runtime for the TUI.\n\nStart it with either:\n\n```bash\nblueferry-tui\nblueferry tui\n```\n\nPress `?` for the keyboard map or `Ctrl+P` for the command palette. The TUI has\nconversation search, a multiline composer, mouse support, themes, and a layout\nthat adapts to narrow terminals.\n\n## Omarchy Quattro\n\nThe native bar panel lives in\n[omarchy-blueferry](https:\u002F\u002Fgithub.com\u002Ferikwb\u002Fomarchy-blueferry):\n\n```bash\nomarchy plugin add https:\u002F\u002Fgithub.com\u002Ferikwb\u002Fomarchy-blueferry.git\n```\n\nEnable it from **Setup › Plugins**. Its popup shows connection health and recent\nconversations; the full Quickshell client handles pairing, messages, and\npreferences.\n\n## Notifications and local data\n\nBlueFerry can show message notifications only—the default—all iPhone\nnotifications, or none. Other app notifications are displayed and discarded;\nthey are not added to message history. Messages seen through both MAP and ANCS\nare deduplicated.\n\nMessage history and contacts are encrypted by default with a random key stored\nin GNOME Keyring or KDE Wallet. If the wallet is locked, live messages continue\nto work, but retained history and contact lookup wait until you unlock it. You\ncan also choose unencrypted storage or **Do not retain local data**. Changing\nstorage modes clears the existing cache so encrypted and plaintext records are\nnever mixed.\n\nConfiguration lives in `~\u002F.config\u002Fblueferry`; local state lives in\n`~\u002F.local\u002Fstate\u002Fblueferry`. Uninstalling packages does not delete either\ndirectory.\n\nThe common retention settings live in `~\u002F.config\u002Fblueferry\u002Flocal.env`:\n\n```bash\nBLUEFERRY_SHOW_NOTIFICATION_CONTENT=false\nBLUEFERRY_NOTIFICATION_TIMEOUT_MS=8000\nBLUEFERRY_HISTORY_RETENTION_DAYS=30\nBLUEFERRY_HISTORY_MAX_EVENTS=10000\nBLUEFERRY_HISTORY_MAX_PAYLOAD_BYTES=268435456\n```\n\nRestart the user service after editing those settings.\n\n## Command line\n\nThe graphical clients cover normal use, but the CLI is useful for diagnostics\nand scripts:\n\n```bash\nblueferry sms-list\nblueferry sms-send '+15551234567' 'on my way'\nblueferry sms-send person@icloud.com 'hello from Linux'\nblueferry sms-send Alice 'running late'\nblueferry contacts-sync\nblueferry history-clear\nblueferry doctor\n```\n\nAmbiguous contact names are presented for you to choose from rather than\nguessed.\n\n## Troubleshooting\n\nStart with the iPhone page in the app. It reports Messages, Contacts, and iPhone\nNotifications separately; messages and contact sync can work even when the\noptional notification connection does not.\n\nFor logs and prerequisite checks:\n\n```bash\nblueferry doctor\njournalctl --user -u blueferry -f\n```\n\nIf messages work but names do not, use **Sync Contacts** or run\n`blueferry contacts-sync`.\n\nPairing failures save a scrubbed report that can be attached to a GitHub issue.\nIt includes the package build and source SHA, pairing mode, controller details,\nand an ordered setup timeline. Please also include the iPhone model and iOS\nversion. Reports remove Bluetooth addresses and home-directory paths, but it is\nstill sensible to inspect anything before posting it publicly.\n\n## Technical details\n\nBlueFerry uses three standard Bluetooth services:\n\n- MAP over Bluetooth Classic carries messages, read state, and sends.\n- PBAP over Bluetooth Classic supplies contacts.\n- ANCS over Bluetooth LE supplies optional notifications and group-message\n  display information.\n\nOne unprivileged per-user backend owns those connections and exposes a small\nsession D-Bus API to the clients. Pairing uses normal Bluetooth confirmation;\nthere is no hidden Apple protocol.\n\nThe deeper design and protocol notes live in\n[ARCHITECTURE.md](ARCHITECTURE.md), [PROTOCOL.md](PROTOCOL.md), and\n[TESTING.md](TESTING.md).\n\nBlueFerry began from\n[iphonebridge](https:\u002F\u002Fgithub.com\u002Fgabrielmeir53\u002Fiphonebridge), created by Gabe\nShatunovsky. The ANCS constants and wire-format code are adapted from\n[ANCS4Linux](https:\u002F\u002Fgithub.com\u002Fbmh129\u002Fancs4linux), by Paweł Zmarzły and\nBradley Harmon, under GPL-2.0-or-later.\n\nBlueFerry is licensed under [GPL-2.0-only](LICENSE).\n","BlueFerry 是一款在 Linux 桌面端本地收发 iPhone 短信（SMS）和 iMessage 的开源工具，通过蓝牙直连 iPhone，无需 Mac 中继、iCloud 同步或任何云端服务。其核心功能包括双向消息收发、联系人同步、已读状态同步、本地加密消息历史存储（支持 GNOME Keyring\u002FKDE Wallet），并提供 GTK、Qt、Quickshell 和终端多种客户端界面。项目依赖 iOS 设备的蓝牙协议层通信，目前处于实验阶段，适用于对隐私敏感、希望在 Linux 上原生使用 iPhone 消息功能的用户，但暂不支持附件、MMS、RCS、群组完整成员识别及历史消息回溯。","2026-08-15 02:30:05","CREATED_QUERY"]