Metadata-Version: 2.4
Name: chatwire
Version: 0.4.1
Summary: macOS chat-relay bridge: iMessage <-> Telegram, web UI, and pluggable integrations
Author: Allen Bina
License: MIT License
        
        Copyright (c) 2026 Allen Bina
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/allenbina/chatwire
Project-URL: Issues, https://github.com/allenbina/chatwire/issues
Keywords: imessage,telegram,macos,bridge,relay
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-telegram-bot<22,>=21.0
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: pywebpush>=2.0
Requires-Dist: httpx
Requires-Dist: jsonschema>=4
Dynamic: license-file

# chatwire

Relay iMessages from a macOS host to other places — currently a Telegram bot
and a web UI, with more integrations planned.

> Originally branded `chat-bridge`; renamed to `chatwire` for v0.2.0 because
> PyPI's similarity check rejected `chat-bridge` (collides with an unrelated
> `chatbridge` package).

> **Status:** alpha. The author runs this daily; nobody else has installed it
> yet. Things will change. See [`docs/OPEN_SOURCE_PLAN.md`](docs/OPEN_SOURCE_PLAN.md)
> for the roadmap.

## What it does

- **Inbound.** A small Python service polls `~/Library/Messages/chat.db`,
  resolves senders against Contacts.app, and forwards messages (text, photos,
  videos, attachments) to your configured integrations.
- **Outbound.** Reply from your phone, your laptop, anywhere — the service
  drives Messages.app via AppleScript to send back as you.
- **Group chats.** First-class. Replies route by chat GUID, not the sender's
  1:1 handle, so you can keep a group conversation in Telegram or the web UI
  and replies land back in the group.

## Constraints

iMessage is Mac-only. The bridge has to live on a Mac with the user's Apple
ID logged into Messages.app, granted Full Disk Access (to read `chat.db`)
and Automation→Messages (to send). macOS gates both behind System Settings
clicks that no installer can bypass — the setup wizard makes them as short
as possible, but you will click through some prompts the first time.

Tested on macOS 12 Monterey. macOS 13–15 should work; not yet smoke-tested.
See `docs/OPEN_SOURCE_PLAN.md` for the support matrix.

## Install

Recommended path: **pipx**, against python.org's Python.

```bash
# Install python.org Python first if you don't have it:
#   https://www.python.org/downloads/macos/
# (Homebrew Python works but TCC treats it as a different identity —
# you'd have to grant Full Disk Access + Automation to that binary
# specifically. python.org is the well-trodden path.)

# Install pipx if you don't have it (once per machine):
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install chatwire from PyPI:
pipx install --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
    chatwire

# Wire it up:
chatwire install-agents
chatwire setup
```

The setup wizard walks you through the Telegram bot token, the macOS
permission grants (Full Disk Access + Automation→Messages), and writes
`~/.chatwire/config.json`.

### Alternate install methods

**Homebrew tap.** Convenient if you already use brew.

```bash
brew install allenbina/tap/chatwire
chatwire install-agents
chatwire setup
```

Tap source: <https://github.com/allenbina/homebrew-tap>.

**curl-pipe-bash.** No PyPI access, no Homebrew, just a shell.

```bash
curl -fsSL https://raw.githubusercontent.com/allenbina/chatwire/main/scripts/install.sh | bash
```

Pin to a tag with `CHATWIRE_REF=v0.2.0`. The script refuses Xcode CLT's
Python stub and warns on Homebrew Python (TCC identity protection). Same
post-install steps (`chatwire install-agents` etc.).

**Developer / git-clone path.** For hacking on the bridge itself:

```bash
git clone https://github.com/allenbina/chatwire.git ~/projects/chatwire
cd ~/projects/chatwire
python3 -m venv .venv
.venv/bin/pip install -e .

# Render and load the launchd agents:
.venv/bin/chatwire install-agents

# (legacy installs only) one-shot migration from ~/.imessage-tg/.env:
.venv/bin/chatwire migrate

# Sanity check:
.venv/bin/chatwire doctor
```

Configure `~/.chatwire/config.json` (chmod 600). Schema:

```json
{
  "version": 1,
  "TELEGRAM_BOT_TOKEN": "...",
  "TELEGRAM_ALLOWED_USER_IDS": "123456789",
  "SELF_HANDLES": "+1XXXXXXXXXX,you@icloud.com",
  "WEB_PORT": "8723"
}
```

The setup wizard (Phase 2) will write this for you. Until then it's hand-edited.

## macOS permissions

Both the FDA grant and the Automation→Messages grant need to be given to the
**python.org Python binary** (not Homebrew's), because the python.org
installer ships two Mach-O binaries with different code-signing identities
that TCC tracks separately. See
[`docs/REFERENCE_INSTALL.md`](docs/REFERENCE_INSTALL.md) section 5 for the
full walkthrough — that section was the reason the bridge worked at all on
the first install, and it's the same on every Mac.

`scripts/check-permissions.sh` (or `chatwire doctor`) will tell you
which prompts you still need to click.

## Privacy

**No telemetry.** chatwire collects no analytics, sends no usage data, and
includes no third-party SDKs that report back. Your messages, contacts,
and `chat.db` stay on your Mac; outbound traffic only goes to integrations
you configure (e.g. Telegram via your own bot token).

Two narrow third-party requests the web UI does make, neither carrying any
of your data:

- The update-check banner fetches `api.github.com/repos/<repo>/releases/latest`
  once a day to surface new-version notices. Disable by setting
  `UPDATE_CHECK_REPO=""` in the launchd agent's environment.
- Static assets (htmx, emoji-picker-element) load from `unpkg.com` and
  `cdn.jsdelivr.net`.

## Repo layout

```
bridge.py             telegram bot + outbound (TG -> iMessage)
chat_db.py            reads chat.db, HEIC -> JPEG via sips
chat_send.py          osascript wrappers (send_text, send_file)
prefix.py             message prefix formatter + reply parser
config.py             config.json loader (with .env fallback)
chatwire_cli.py       setup / install-agents / logs / doctor / migrate
contacts.py           Contacts.app -> handle/name lookup
echo_log.py           cross-process echo dedup
whitelist.py          runtime-mutable allowlist
_version.py           release-semver source of truth
web/                  FastAPI web UI + first-run setup wizard
migrations/           config-schema migration runner
templates/launchd/    plist templates rendered by install-agents
scripts/install.sh    curl-pipe-bash installer (alternative to brew)
docs/                 OPEN_SOURCE_PLAN.md, REFERENCE_INSTALL.md
```

## Trademarks

iMessage, Messages, macOS, and AppleScript are trademarks of Apple Inc.,
referenced here in their descriptive sense — this project relays to and
from Apple's iMessage service. **chatwire is not affiliated with,
endorsed by, or sponsored by Apple Inc.**

## License

MIT — see [`LICENSE`](LICENSE).

## Contributing

Not accepting PRs yet — Phase 1 is mid-flight. Open an issue if you have
questions or hit a wall installing.
