Install with pipx (recommended)¶

pipx installs Python CLI tools into isolated virtualenvs, keeping chatwire's dependencies separate from everything else on your system. Combined with python.org Python, it gives you the most reliable TCC permission experience on macOS.

Prerequisites¶

1. Python from python.org¶

Download and install the latest stable Python 3 from https://www.python.org/downloads/macos/. Run the .pkg installer — it places Python at:

/Library/Frameworks/Python.framework/Versions/3.13/bin/python3.13

Do not use Homebrew Python or the Xcode CLT stub. macOS TCC tracks Full Disk Access and Automation grants per binary identity. python.org's framework binary is the well-trodden path — grants survive upgrades and don't require re-granting when chatwire updates.

Verify the install:

/Library/Frameworks/Python.framework/Versions/Current/bin/python3 --version
# Python 3.13.x

2. pipx¶

python3 -m pip install --user pipx
python3 -m pipx ensurepath

Then restart your terminal (or run source ~/.zshrc / source ~/.bash_profile) so ~/.local/bin is on your PATH.

Verify:

pipx --version
# 1.x.x

Install chatwire¶

pipx install \
  --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
  chatwire

Expected output:

  installed package chatwire 1.x.x, installed using Python 3.13.x
  These apps are now globally available
    - chatwire
    - chatwire-toolbar
done! ✨ 🌟 ✨

If you see WARNING: chatwire is running under a Python whose base prefix is..., your pipx resolved to a different Python. Re-run with the explicit --python flag above.

Install a specific version¶

pipx install \
  --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 \
  "chatwire==1.5.0"

Set up the background services¶

chatwire install-agents

This renders plist templates and installs three launchd agents in ~/Library/LaunchAgents/:

Agent	Role
`dev.chatwire.bridge`	Polls chat.db every 2 seconds
`dev.chatwire.web`	Serves the web UI on port 8723
`dev.chatwire.keepawake`	Keeps macOS awake while the bridge is active

Expected output:

wrote /Users/you/Library/LaunchAgents/dev.chatwire.bridge.plist
loaded dev.chatwire.bridge.plist
wrote /Users/you/Library/LaunchAgents/dev.chatwire.web.plist
loaded dev.chatwire.web.plist

Keep-awake: chatwire needs your Mac awake to relay messages.
...

Run the setup wizard¶

chatwire setup

This opens the web wizard at http://127.0.0.1:8723/setup — or prints the URL if your browser doesn't open. See First run for the full wizard walkthrough.

Run the pre-flight check¶

chatwire doctor

All critical checks (Full Disk Access, Automation → Messages) must show ✓ before the bridge can relay messages. See macOS permissions for grant instructions.

Upgrade chatwire¶

pipx upgrade chatwire

Then restart the agents:

launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge
launchctl kickstart -k gui/$(id -u)/dev.chatwire.web

Or use the restart buttons in Settings → About in the web UI.

Install plugins¶

Plugins are injected into chatwire's pipx virtualenv so they share its Python environment:

pipx inject chatwire chatwire-ntfy
pipx inject chatwire chatwire-telegram

After injecting, restart the bridge agent:

launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

Then enable the plugin in Settings → Plugins.

To remove a plugin:

pipx uninject chatwire chatwire-ntfy

Uninstall¶

Preserve config and data (reinstalling picks up where you left off):

chatwire uninstall
pipx uninstall chatwire

Remove everything including config and logs:

chatwire uninstall --purge
pipx uninstall chatwire

Preview what --purge would remove before committing:

chatwire uninstall --purge --dry-run

Troubleshooting¶

See Troubleshooting for common issues. The most frequent pipx-specific problem is using the wrong Python binary — always pass --python /Library/Frameworks/Python.framework/Versions/Current/bin/python3 on the initial install.