FAQ¶
General¶
What does chatwire actually do?¶
chatwire reads your iMessage database (~/Library/Messages/chat.db) and gives you a web UI, Telegram relay, push notifications, and automation rules for your messages — running entirely on your Mac with no cloud servers.
Does chatwire work without a Mac?¶
No. iMessage is Apple-only. The bridge needs a Mac with your Apple ID signed into Messages.app. It can serve any device — iPhone, Android, Windows laptop — as long as those devices can reach the Mac's web server.
Does chatwire modify my messages or Messages.app?¶
chatwire only reads chat.db — it never writes to it. Sending messages goes through Messages.app via AppleScript, which is the same thing as typing in Messages.app yourself. Your Apple ID, message history, and Messages.app state are not modified by chatwire.
Is this against Apple's Terms of Service?¶
chatwire reads your own database, on your own computer, with permissions you explicitly grant. It doesn't reverse-engineer any Apple protocol or access Apple's servers. Using your own data on your own hardware is not a TOS violation.
Why doesn't Apple just build this?¶
iMessage lock-in sells hardware. The green bubble / blue bubble divide is a feature of Apple's business model, not a technical limitation. chatwire exists because Apple made a business decision — not a technical one.
Installation¶
Why do I need python.org Python specifically?¶
macOS TCC (Transparency, Consent, and Control) tracks permission grants per-binary. Full Disk Access and Automation→Messages are granted to a specific Python executable path. python.org's framework Python is at a predictable, stable path that doesn't change across chatwire upgrades. Homebrew Python and system Python are at different paths and may change when upgraded.
The practical result: with python.org Python, you grant permissions once. With other Python installs, you may have to re-grant after upgrades.
Can I use the system Python that came with macOS?¶
No. The system Python (/usr/bin/python3) is the Xcode CLT stub — it lacks the framework headers and behaves unexpectedly with TCC. chatwire warns about this and exits if it detects the system stub.
Does chatwire run on Linux or Windows?¶
No. The bridge needs ~/Library/Messages/chat.db (macOS-only), Messages.app (macOS-only), and AppleScript (macOS-only). The web UI and mobile app run anywhere, but the bridge itself requires a Mac.
Permissions¶
The wizard says my Python isn't in the Automation list yet. What do I do?¶
macOS only adds an app to the Automation list after it tries to control another app. To trigger the first prompt:
- Open Script Editor (Applications/Utilities)
- Paste and run:
tell application "Messages" to get every service - Grant the dialog that appears
- Your Python binary should now appear in System Settings → Privacy & Security → Automation
I granted Full Disk Access but chatwire doctor still shows ✗.¶
Make sure you granted access to the right binary — the one chatwire actually runs as. Check the path in chatwire doctor. If it doesn't match what you added in System Settings, add the correct path and try again.
After granting, restart the bridge:
Messages and relay¶
Why does my contact whitelist matter?¶
The whitelist controls which contacts' messages chatwire relays. Without a whitelist entry, messages from a contact stay in Messages.app on your Mac and don't appear in the chatwire web UI, Telegram relay, or any integration.
Start with the contacts you actually want to relay. You can add more from Settings → Whitelist at any time.
Can other people see my messages through chatwire?¶
Only if they can reach the URL. By default chatwire binds to 127.0.0.1 — only requests from your Mac. If you expose it on your LAN or via Tailscale, anyone on the same network can reach it. Add a web UI password and use Tailscale or Cloudflare Access for external access.
Does chatwire read all my messages, including from people not on my whitelist?¶
The bridge reads chat.db to detect new messages — it must scan all rows. But it only relays messages from whitelisted contacts. Messages from contacts not on the whitelist are seen but dropped immediately. They never reach the web UI, Telegram, ntfy, or any plugin.
Plugins and themes¶
How do I install a plugin?¶
Then enable it in Settings → Plugins. See Plugins.
Can I build my own plugin?¶
Yes. See the Plugin SDK guide. Plugins are Python packages that declare a chatwire.integrations entry point. The SDK provides the BaseIntegration class, scaffold CLI, and documentation.
How do I add a theme?¶
Drop a .json file in ~/.chatwire/themes/. It appears in Settings → Themes → Theme Packages. No restart needed. See Theme format for the full spec.
Comparison¶
How is chatwire different from BlueBubbles?¶
BlueBubbles requires a .NET server, a Firebase project for push notifications, and Google Cloud credentials. chatwire is a single pipx install with no cloud accounts required.
How is chatwire different from AirMessage?¶
AirMessage hasn't been updated since 2023. chatwire is actively developed with 23 themes, a plugin SDK, React UI, PWA support, and mobile app.
How is chatwire different from Beeper (now Texts.com)?¶
Beeper is commercial, closed-source, and $10/month — your messages route through their servers. chatwire is open-source, free, and self-hosted. Your data never leaves your Mac unless you configure an integration.
Troubleshooting¶
chatwire: command not found¶
Run pipx ensurepath and restart your terminal. Or add ~/.local/bin to your PATH manually.
The bridge starts but no messages show up.¶
Check chatwire doctor. The two most common causes:
1. Full Disk Access not granted
2. Whitelist is empty (no contacts configured)
Messages send from the web UI but don't arrive.¶
Confirm Messages.app is open and not in Do Not Disturb mode. Check the bridge log for AppleScript errors: chatwire logs --service bridge -f.
Something else is wrong.¶
Run chatwire doctor, check the logs (chatwire logs -f), and open an issue with the output.