Plugins¶

Plugins extend chatwire with new integrations, notification services, and UI components. They're installed into chatwire's Python virtualenv and discovered automatically at startup.

Available plugins¶

Package	What it adds
`chatwire-ntfy`	Push notifications via ntfy.sh or self-hosted ntfy
`chatwire-telegram`	Relay messages to/from a Telegram bot
`chatwire-webhook`	Forward messages to any HTTP endpoint
`chatwire-mqtt`	Publish messages to an MQTT broker
`chatwire-ha`	Home Assistant integration
`chatwire-xmpp`	XMPP / Jabber relay
`chatwire-theme-rosepine`	Rose Pine theme (Moon / Dawn / Main color schemes)

Installing a plugin¶

Plugins are injected into chatwire's virtualenv:

# With pipx (recommended install path):
pipx inject chatwire chatwire-ntfy

# After installing, restart the bridge:
launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

Plugins are discovered automatically at startup — no config file edit needed to activate the package. After the bridge restarts, the plugin appears in Settings → Plugins.

With uv¶

uv tool install --with chatwire-ntfy chatwire

From a local directory (development)¶

pipx inject chatwire -e /path/to/my-plugin

Enabling a plugin¶

Open Settings → Plugins in the web UI
Find the plugin card and toggle it on
Fill in the required configuration fields (API keys, URLs, etc.)
Click Save
Restart the bridge if the plugin requires it (it will say so in the settings card)

Configuration is stored in ~/.chatwire/config.json (mode 600).

Configuring a plugin¶

Each plugin's settings section is auto-generated from its SETTINGS_SCHEMA. Common field types:

Text input — for tokens, URLs, topic names
Number — for timeouts, intervals, port numbers
Toggle — for on/off options
Dropdown — for enum choices

Plugin settings sections appear in Settings → Plugins as collapsible accordion cards. The card header shows the plugin's display name, description, and enable/disable toggle.

Removing a plugin¶

# With pipx:
pipx uninject chatwire chatwire-ntfy

# Restart the bridge:
launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge

After uninjecting, the plugin disappears from Settings → Plugins. Its configuration block in config.json remains (harmless) until you manually remove it or run chatwire uninstall --purge.

Plugin data¶

Each plugin gets a private directory at ~/.chatwire/plugins/<name>/:

plugin.log — private log file (only when the plugin sets LOGS_VISIBLE = False)
Any plugin-specific state files

Plugin logs with LOGS_VISIBLE = True (the default) appear in Settings → Logs alongside bridge and web logs.

Plugin tiers¶

Plugins declare a tier that determines their data access:

Tier	What the plugin can see	Who can use
`ui`	CSS/JS only — no message data	Anyone
`notify`	Sender name, group info, timestamp	Anyone
`official`	Full message text + send capability	Maintainer-reviewed only
`core`	Full BridgeContext (internal)	Built-in components only

Third-party plugins start at notify. Getting official tier access requires code review by the chatwire maintainer and signing of the published package.

Building a plugin¶

See the Plugin SDK guide for how to build your own plugin.

Troubleshooting plugins¶

Plugin doesn't appear in Settings after install: - Did you restart the bridge? launchctl kickstart -k gui/$(id -u)/dev.chatwire.bridge - Did pipx inject succeed? Check for errors in the terminal output. - Run chatwire status — it lists installed plugins.

Plugin is enabled but not working: - Check Settings → Logs for errors from your plugin's name - Verify configuration values (API keys, URLs, etc.) - Check the plugin's own docs or README for setup requirements

pipx inject fails: - Make sure you're using the pipx install of chatwire, not Homebrew or uv - Try pipx inject chatwire <package> --force to reinstall

Plugin causes bridge crash: - Check ~/Library/Logs/chatwire/stderr.log for the traceback - Disable the plugin in Settings → Plugins (or set enabled: false in config.json) and restart the bridge