Skip to content

Install with Homebrew

If you're already a Homebrew user and comfortable with it, the Homebrew tap is a convenient one-liner. Read the caveats below before choosing this path.

Prerequisites

  • Homebrew installed.
  • macOS 12 Monterey or later.

Install

brew install allenbina/tap/chatwire

This taps allenbina/homebrew-tap if you haven't already, then installs chatwire and its dependencies.

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

Set up background services

chatwire install-agents
chatwire setup

Same as every other install method — install-agents renders the launchd plists; setup runs the first-run wizard.

Upgrade

brew upgrade chatwire

Restart the agents after upgrading:

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

Caveats

TCC permission binding

Homebrew manages its own Python binary, separate from python.org's framework Python. macOS TCC binds Full Disk Access (FDA) and Automation→Messages grants to the specific binary path of the Python executable.

This means: - Your grants are tied to Homebrew's Python (e.g. /usr/local/bin/python3 or /opt/homebrew/bin/python3). - If Homebrew upgrades Python to a new minor version, the binary path changes and you must re-grant both permissions. - If you previously granted FDA to python.org's Python for a different tool, that grant does not carry over to Homebrew's Python.

Run chatwire doctor after any Homebrew Python upgrade to verify permissions are still valid.

Plugin installs

chatwire's plugin injection model uses pipx inject. With a Homebrew install, you won't have a pipx virtualenv — instead, install plugins into the same virtualenv that Homebrew uses, or switch to the pipx install method.

The pipx inject workflow is only available with the pipx install path. If you need plugins with Homebrew, consider switching:

brew uninstall chatwire
# Then follow install/pipx.md

brew services vs launchd

chatwire ships its own launchd plist templates (via chatwire install-agents). You can also use brew services start chatwire, but the plist rendered by chatwire is preferred — it includes the correct log paths and environment variables.

If you used brew services start chatwire and then ran chatwire install-agents, you may have both a Homebrew service plist and a chatwire plist loaded. Check with:

launchctl list | grep chatwire

Duplicate entries for the same role will cause the second one to fail to bind the port. Unload the Homebrew one:

brew services stop chatwire

Uninstall

# Remove the package (preserves ~/.chatwire/ config and data)
brew uninstall chatwire

# Also remove the tap if you don't use it for anything else
brew untap allenbina/tap

# Interactively remove config and data
chatwire uninstall --purge

Troubleshooting

If chatwire doctor shows permission failures after a Homebrew Python upgrade:

  1. Open System Settings → Privacy & Security → Full Disk Access
  2. Locate the old Python entry and toggle it off
  3. Click + and navigate to the new Homebrew Python binary (shown in chatwire doctor)
  4. Toggle it on
  5. Repeat for Automation → Messages
  6. Restart the bridge: launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

See macOS permissions for full grant instructions and the troubleshooting guide for more.