Skip to content

Configuration

Jump to bottom
ekollof edited this page Jun 5, 2026 · 8 revisions

Configuration

Creating an account

/account add <name> <jid> <password>
  • <name> — a short local label for this account (e.g. work, personal)
  • <jid> — your Jabber ID, e.g. user@example.com
  • <password> — your XMPP account password

Connect / disconnect

/account connect <name>
/account disconnect <name>
/account reconnect <name>

List / remove accounts

/account list
/account delete <name>

Accounts are stored in the WeeChat config file ~/.config/weechat/plugins.conf (or ~/.weechat/plugins.conf on older setups).

In-Band Registration (XEP-0077)

If your XMPP server supports in-band registration you can create and manage accounts directly from WeeChat:

/account register <name> <jid> <password>   # register a new account on the server
/account unregister <name>                  # cancel account registration
/account password <name> <new-password>     # change password (requires TLS)

Note: /account register connects to the server without authenticating first and registers the account; it then calls /account add automatically so the account is available for normal use. If the server requires CAPTCHA or extra fields, a message is shown and registration is aborted.

Plugin options

All plugin options live under the xmpp namespace. List them with:

/set xmpp.*

Use /fset xmpp for a full interactive list with descriptions.

Key options

Option Default Description
xmpp.look.debug off Route protocol messages to an xmpp.debug buffer
xmpp.look.raw_xml_log off Log every XML stanza to ~/.local/share/weechat/xmpp/raw_xml_<account>.log
xmpp.look.outgoing_link_preview on Auto-fetch OpenGraph metadata for URLs you send (XEP-0511)
xmpp.look.incoming_link_preview on Display OpenGraph link previews received from other users (XEP-0511)
xmpp.look.smart_filter on Hide join/leave/nick-change spam for quiet occupants
xmpp.look.omemo_atm on Enable Automatic Trust Management (XEP-0450) — TOFU + cross-device trust propagation

Save settings with /save or they are written automatically when WeeChat exits.

Status bar items

Encryption indicator

Shows the current buffer's encryption mode: OMEMO, PGP, or empty for plaintext.

Add it to your status bar (edit to taste):

/set weechat.bar.status.items "[time],[buffer_last_number],[buffer_plugin],buffer_number+:+buffer_name+(buffer_modes)+{buffer_nicklist_count}+buffer_zoom+buffer_filter,xmpp_encryption,[lag],[hotlist],completion"
/save

The (buffer_modes) slot is automatically populated for MUC rooms with the IRC-style mode string (e.g. +miP for a moderated, members-only, persistent room). See Command-Reference → "Room mode letters" for the full legend. Use /modes in a MUC buffer to print all room metadata.

Typing indicator

  1. Enable the WeeChat typing plugin settings:

    /set typing.look.enabled_nicks on
/set typing.look.enabled_self on
/set typing.look.input_min_chars 2
/save typing

  2. Make sure typing is in your status or typing bar:

    /set weechat.bar.typing.items "typing"
/save

When another user is composing a message you will see their nick appear in the typing bar (XEP-0085).

Autojoin bookmarks

MUC rooms can be bookmarked with autojoin enabled so they are joined automatically on connect (XEP-0402 PEP Native Bookmarks).

/bookmark add room@conference.example.com "My Room"
/bookmark autojoin room@conference.example.com on

Bookmarks are stored server-side via PEP and survive client changes.

Encryption defaults

OMEMO

OMEMO is disabled by default for new conversations and must be enabled per-buffer:

/omemo

Note: OMEMO works in both PM and non-anonymous MUC buffers. MUC OMEMO (multi-recipient) is experimental and untested — exercise caution. See docs/planning-muc-omemo.md in the main repo for current status.

Once you send an OMEMO-encrypted message to a contact, the plugin will auto-enable OMEMO for that conversation when the contact replies with an encrypted message.

PGP

/pgp <keyid>      # set your PGP key
/pgp status       # show current key
/pgp reset        # clear key

Disabling encryption

/plain

Nick-color generation

Nick colors follow XEP-0392: Consistent Color Generation, producing the same color for a given nick across all compliant clients. No configuration is needed.

Smart presence filter

The smart filter hides join/leave/nick-change notices for MUC occupants who have not spoken recently — matching IRC client behavior.

The filter tag is xmpp_smart_filter. WeeChat applies it via a global filter named xmpp_smart_filter_default that is created automatically on plugin load:

/filter list     # see all filters

To temporarily show all presence lines in a buffer:

/filter toggle xmpp_smart_filter_default

Clone this wiki locally