Install with uv¶

uv is a fast, modern Python package manager written in Rust. uv tool install gives you an isolated tool environment similar to pipx, but significantly faster.

Prerequisites¶

Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or via Homebrew:

brew install uv

You also need python.org Python for the best TCC experience — see Install with pipx for the reasoning.

Install chatwire¶

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

uv places the tool environment under ~/.local/share/uv/tools/chatwire/ and puts the chatwire binary on your PATH via ~/.local/bin/.

Verify:

chatwire --version
# chatwire 1.x.x

Install a specific version¶

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

Set up and run¶

chatwire install-agents
chatwire setup
chatwire doctor

Identical to the pipx path — the agents and wizard work the same way regardless of install method.

Upgrade¶

uv tool upgrade chatwire

Restart agents after upgrading:

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

Install plugins¶

uv tool environments support adding packages similarly to pipx:

uv tool install --with chatwire-ntfy chatwire

Or after the initial install:

uv tool run --with chatwire-ntfy chatwire  # one-shot with the plugin

For persistent plugin installs, add them to the tool's environment:

uv tool install --with chatwire-ntfy --with chatwire-telegram chatwire

Note: unlike pipx inject, uv reinstalls the tool with the new packages rather than injecting into the existing environment. The result is the same — the bridge starts with all listed plugins available.

Restart the bridge after changing plugins:

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

Caveats¶

TCC permission binding¶

Same as Homebrew: TCC grants bind to the specific Python binary. Pass --python /Library/Frameworks/Python.framework/... when installing to use python.org's binary — grants will then survive uv upgrades (which don't change the underlying Python).

If you didn't pass --python on the initial install, check which Python uv resolved:

chatwire doctor
# look for the Python binary path in the output

If it's not under /Library/Frameworks/Python.framework/, reinstall with the explicit path.

Auto-detection¶

chatwire doctor and chatwire status detect the install method:

Install method detected: uv (upgrade: uv tool upgrade chatwire)

The uninstall command is likewise method-aware:

chatwire uninstall
# prints: uv tool uninstall chatwire

Uninstall¶

uv tool uninstall chatwire

# Also remove config and data:
chatwire uninstall --purge

Troubleshooting¶

See Troubleshooting. The uv path is functionally identical to pipx — if you hit permission issues, the same TCC grant steps apply. Run chatwire doctor to identify which binary needs the grant.