weechat-matrix/README.md

What is Weechat-Matrix?

Weechat is an extensible chat client.

Matrix is an open network for secure, decentralized communication.

Weechat-Matrix is a Python plugin for Weechat that lets Weechat communicate over the Matrix protocol.

Project Status

Weechat-Matrix already supports large parts of the Matrix protocol, end to end encryption support is still experimental.

Installation

1. Install libolm 3.1+

   • Debian/Ubuntu install libolm-dev if new enough

   • Archlinux based distribution (see https://aur.archlinux.org/packages/libolm/) use your favorite pacman frontend with AUR support (yaourt, yay, pikaur, …)

   • Failing any of the above see https://git.matrix.org/git/olm for instructions about building it from sources

2. Clone the repo and install dependencies

   git clone https://github.com/poljar/weechat-matrix.git
   cd weechat-matrix
   pip install -r requirements.txt
   

3. As your regular user, just run: make install in this repository directory.

   This installs the main python file (main.py) into ~/.weechat/python/ (renamed to matrix.py) along with the other python files it needs (from the matrix subdir).

   Note that weechat only supports Python2 OR Python3, and that setting is determined at the time that Weechat is compiled. Weechat-Matrix can work with either Python2 or Python3, but when you install dependencies you will have to take into account which version of Python your Weechat was built to use.

   The minimal supported python2 version is 2.7.10.

   To check the python version that weechat is using, run:

    /python version
   

Using virtualenv

If you want to install dependencies inside a virtualenv, rather than globally for your system or user, you can use a virtualenv. Weechat-Matrix will automatically use any virtualenv it finds in a directory called venv next to its main Python file (after resolving symlinks). Typically, this means ~/.weechat/python/venv.

To create such a virtualenv, you can use something like below. This only needs to happen once:

virtualenv ~/.weechat/python/venv

Then, activate the virtualenv:

. ~/.weechat/python/venv/bin/activate

This needs to be done whenever you want to install packages inside the virtualenv (so before running the pip install command documented above.

Once the virtualenv is prepared in the right location, Weechat-Matrix will automatically activate it when the plugin is loaded. This should not affect other plugins, which seem to have a separate Python environment.

Note that this only supports virtualenv tools that support the activate_this.py way of activation. This includes the virtualenv command, but excludes pyvenv and the Python3 venv module. In particular, this works if (for a typical installation of matrix.py) the file ~/.weechat/python/venv/bin/activate_this.py exists.

Uploads

Uploads are done using a helper script, the script found under contrib/matrix_upload should be installed under your PATH.

Configuration

Configuration is completed primarily through the Weechat interface. First start Weechat, and then issue the following commands:

1. Start by loading the Weechat-Matrix plugin:

   /script load matrix.py
   

2. Now set your username and password:

   /set matrix.server.matrix_org.username johndoe
   /set matrix.server.matrix_org.password jd_is_awesome
   

3. Now try to connect:

   /matrix connect matrix_org
   

4. If everything works, save the configuration

   /save
   

For using a custom (not matrix.org) matrix server:

1. Add your custom server to the plugin:

   /matrix server add myserver myserver.org
   

2. Add the appropriate credentials

   /set matrix.server.myserver.username johndoe
   /set matrix.server.myserver.password jd_is_awesome
   

3. If everything works, save the configuration

   /save
   

Bar items

There are two bar items provided by this script:

1. matrix_typing_notice - shows the currently typing users

2. matrix_modes - shows room and server info (encryption status of the room, server connection status)

They can be added to the weechat status bar as usual: /set weechat.bar.status.items

The matrix_modes bar item is replicated in the already used buffer_modes bar item.

Typing notices and read receipts

The sending of typing notices and read receipts can be temporarily disabled via the /room command, they can also be permanently configured using standard weechat conditions settings with the following settings:

1. matrix.network.read_markers_conditions
2. matrix.network.typing_notice_conditions

Helpful Commands

/help matrix will print information about the /matrix command.

/help olm will print information about the /olm command that is used for device verification.

/matrix help [command] will print information for subcommands, such as /matrix help server