Skip to content

chatwire documentation

chatwire is a self-hosted iMessage bridge that runs on your Mac and gives you access to your messages from any browser, phone, or Telegram — with zero telemetry and no third-party servers.

What chatwire does

  • Reads your messages. A background bridge polls ~/Library/Messages/chat.db and surfaces every conversation in a modern web UI.
  • Sends messages as you. Reply from any browser tab or from Telegram; the bridge drives Messages.app via AppleScript so messages go out as normal iMessages or SMS.
  • Relays to integrations. Telegram relay, ntfy push notifications, webhooks, MQTT, Home Assistant, XMPP — install only what you need.
  • Extends via plugins. A typed SDK lets third-party packages add new integrations, settings UI sections, and sidebar widgets.

Install

# Recommended path: pipx with python.org Python
python3 -m pip install --user pipx && python3 -m pipx ensurepath
pipx install --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 chatwire
chatwire install-agents
chatwire setup

Then open http://localhost:8723.

Documentation sections

Install

Page What it covers
Choose your install method Decision tree — pipx vs Homebrew vs uv vs DMG
pipx (recommended) Full pipx walkthrough with python.org Python
Homebrew brew tap + install + caveats
uv uv tool install — fast, modern alternative
Standalone / DMG Future Tauri app
macOS permissions FDA + Automation TCC grants
First run chatwire init walkthrough, web wizard
Troubleshooting Common issues and fixes

User guide

Page What it covers
User guide overview Feature map and navigation
Web UI tour Layout, sidebar, chat view, keyboard shortcuts
Sending messages Compose, reply, groups, attachments, reactions
Notifications Push via ntfy, connection banner, sounds
Telegram relay Bot setup, relay commands, group routing
Automation rules Rules engine: conditions, actions, DSL
Themes Theme picker, custom CSS, scheme vs style
Plugins Install, remove, configure plugins
MCP integration Scopes, tools, LLM client setup
Mobile app React Native app — connect, features, build
Security Fuse system, password, API keys
FAQ Frequently asked questions

Developer reference

Page What it covers
Developer guide overview Architecture summary and contribution paths
Architecture Bridge → web → frontend → plugins in depth
Contributing Clone, deps, tests, PR process
Plugin SDK Entry points, hooks, slot API, settings schema
Theme format CSS variables, scheme/style, packaging
API reference REST + SSE + MCP endpoints
Testing pytest + vitest + mobile Jest
Release process Versions, PyPI, Homebrew, changelogs