WeeChat

WeeChat is a highly extendable and feature rich IRC client.

Installation

Install the weechat package, or weechat-git^AUR for the development version.

Usage

WeeChat provides two executables:

weechat, the curses interface, see
, the headless version, see

Read the quick start guide. For details consult the user's guide.

Configuration

By default WeeChat stores its configuration files in XDG directories. Editing these files directly is not recommended because WeeChat may write them at any time.

Instead you should use the /set command. You can get a list of all configurable options by running /set in the WeeChat buffer window. Since there are nearly 600 default configurable options, you can search through them with a wildcard syntax: or /set *server* as an example. You can get help on each option with the command:

/help irc.server.libera.autoconnect

Connecting to a server

You can connect to a IRC server by adding it and then using :

/server add libera irc.libera.chat/6667
/connect libera

See the WeeChat documentation and for more information.

Configuring SSL

Many IRC servers, including libera where #archlinux is, support SSL.

If you are making a server with , add the SSL port (usually 6697) and -ssl to the end of the line. For example:

/server add libera irc.libera.chat/6697 -ssl

Tips and tricks

Upgrading

WeeChat can be upgraded without disconnecting from the IRC servers (non-SSL connections only):

/upgrade

This will load the new WeeChat binary and reload the current configuration.

Aliases

Aliases can be created to simplify commonly executed commands. A nice example is Wraithan's smart filter alias:

Smart Filter

First, we need to enable smart filters:

/set irc.look.smart_filter "on"

Next, we will create the sfilter alias:

/alias add sfilter filter add irc_smart_$server_$channel irc.$server.$channel irc_smart_filter *

We can now type

/sfilter

in any buffer, and the smart filter will only be enabled for that buffer.

The following alias will remove a previously enabled smart filter in the current buffer. Add the alias:

/alias add rmsfilter filter del irc_smart_$server_$channel

and execute it by

/rmsfilter

Exec command

A new plugin called "exec" has been added, with command /exec. It will execute external command and can display output to the current buffer with the -o option or locally (default).

Key bindings

See .

Example that adds basic irssi style window scrolling:

/key bind meta-p /window page_up
/key bind meta-n /window page_down

If you are using vimode plugin, most of the default bindings will not work will have vim like alternatives. Check bindings

SSH connection lost when idle

If you are connecting to your WeeChat through a remote shell using SSH, for example running it in GNU Screen or tmux you might experience getting disconnected after a while when idle. There are multiple factors in play why this might happen, but the easiest way to change this is to force the connection to be kept alive by appending this to your SSH-configuration on the remote shell.

This has nothing to do with WeeChat itself, but losing connection when idle will not happen with its alternative irssi by default, and thus is a common situation for those converting to WeeChat.

Or have a look at Mosh.

Emojis

Emojis are part of Unicode set. Requirements for emojis to work:

terminal emulator must support Unicode and emojis subset. For example, rxvt Unicode (urxvt) does not support emojis.
font used in terminal emulator must support emojis subset.

Incomplete list of terminals with emojis support:

xfce4-terminal
alacritty

Mouse support

A terminal emulator will pass through mouse scroll events and weechat will scroll in areas

chat area
nicklist bar

Mouse in tmux

When running in tmux turn on mouse support in ~/.tmux.conf:

set -g mouse on

Matrix

The script allows you to connect to Matrix servers. Install it, then:

run inside Weechat,
configure weechat-matrix, and
use the command inside a Matrix buffer to join Matrix channels, e.g. .

To load the script automatically during WeeChat startup, run:

$ mkdir -p ~/.local/share/weechat/python/autoload
$ ln -s /usr/share/weechat/python/weechat-matrix.py -t ~/.local/share/weechat/python/autoload

Slack

There is a native client for slack: wee-slack

Desktop notifications

To receive desktop notifications for mentions or private messages, the weechat-notify-send script by Petr Zemek can be used.

To install, use:

cd ~/.local/share/weechat/python
curl -O https://raw.githubusercontent.com/s3rvac/weechat-notify-send/master/notify_send.py
ln -s ../notify_send.py autoload/

The script uses and is known to work with both KDE and Gnome.

Another alternative with the built-in plugin is to set a value for trigger.trigger.beep.command.

 /set trigger.trigger.beep.command "/print -beep;/exec -bg notify-send -i '/usr/share/icons/hicolor/32x32/apps/weechat.png' 'IRC Notification' "${tg_tag_nick}: ${tg_message_nocolor}""

Mobile device notifications

To receive notifications for mentions or private messages to an Android mobile device, you can use the IrssiNotifier port to WeeChat from here. This script requires a Google Account, and a registration step with the service provider to obtain an API key. Then, install the plugin

cd ~/.local/share/weechat/python
curl -O https://www.weechat.org/files/scripts/irssinotifier.py
ln -s ../irssinotifier.py autoload/

and intialize the API token and end-to-end encryption password in WeeChat

/set plugins.var.python.irssinotifier.api_token your-api-token-from-website
/set plugins.var.python.irssinotifier.encryption_password your-password-same-as-in-andoid-app
/save

An alternative that does not require a Google Account is a Ruby script for NotifyMyAndroid.com from here, with a similar installation procedure to the above, but into .

WeeChat relay with a systemd user service

To use your WeeChat instance as a WeeChat relay for other WeeChat clients (not to be confused with the IRC relay feature) you can use the WeeChat relay plugin and either a systemd user service, if you only want headless operation, or a combination of a systemd user service and tmux to maintain full command line functionality.

Either method involves creating a service file in the directory

tmux method

Due to the incompatibilities between how systemd manages jobs and the client-server behavior of tmux you will want to use the option to separate your default tmux sessions from the WeeChat one being managed by systemd. If this is the first tmux session started using the default socket then stopping and restarting the WeeChat user service will kill all the sessions connected to the default tmux socket. If the WeeChat tmux session is started after another default tmux session then the WeeChat session will die once systemd moves onto the next service unit. Sequestering the WeeChat tmux server to its own socket forces the expected behaviors when invoking systemctl. This does however mean that you will not see the WeeChat session when using tmux without using to select the correct socket.

~/.config/systemd/user/weechat.service

[Unit]
Description=A WeeChat client and relay service using Tmux
After=network.target

[Service]
Type=forking
RemainAfterExit=yes
ExecStart=/usr/bin/tmux -L weechat new -d -s weechat weechat
ExecStop=/usr/bin/tmux -L weechat kill-session -t weechat

[Install]
WantedBy=default.target

Once the service is in place, all you need to do is start/enable the user unit and run .

From there you can connect to the tmux session in order to configure the weechat relay plugin:

$ tmux -L weechat attach

From there you can configure the WeeChat relay plugin with the desired settings on the console: https://www.weechat.org/files/doc/stable/weechat_user.en.html#relay_plugin

If you want to hide tmux status bar, you can append this option to :

\; set-option status off

For displaying 256 colors with the session it may be needed to append this to tmux configuration file:

set -g default-terminal screen-256color

Headless method

A key difference with this method is that you will either need to start WeeChat normally, configure the relay plugin, stop WeeChat, and then start the service or edit your file manually while WeeChat is not running and then start your service. Either way you will need to configure your relay settings before starting your systemd WeeChat service: https://www.weechat.org/files/doc/stable/weechat_user.en.html#relay_plugin.

Note that we do not need an defined because systemd will automatically track the PID and send the appropriate shutdown signal to the daemon.

Once the user unit is in place, enable it. When you are ready to start your headless relay, start the user unit.

Troubleshooting

Errors loading plugins

You may see output like the following in the main window after starting weechat:

The default configuration for weechat attempts to load all plugins found in /usr/lib/weechat/plugins which in this case includes ruby, lua, aspell and tcl. These packages are not required by the weechat package and may not be installed on your machine. There are two options if these errors bother you:

Install , , and/or .
Or, run which will prevent loading those plugins with a bang (!) prefix.

Problem loading multiline.pl

This problem happens with perl version >= 5.31.1

The script depends on the module. However, since perl version v5.31.1 has been removed.

To fix the problem, install .

Getting help

To access WeeChat's built-in help, simply type

/help

and the help will be displayed in the main buffer (usually buffer 1).

gollark: I don't think it's that *new*.

gollark: Thanks, MPs!

gollark: I heard of some cheap SiFive thingy or something...

gollark: `[...] and so the Librem 5 comes with a standard 3.5mm headphone jack. The Courage Jack.`

gollark: It's probably so expensive because:- basically nobody else is selling similar things so they can pricegouge to death- fewer economies of scale- they're going for really really FOSS stuff, so they have fewer options for components- they will have to develop a lot of the software from scratchhttps://puri.sm/products/librem-5/ @abnormal