{"id":13467217,"url":"https://github.com/poljar/weechat-matrix","last_synced_at":"2025-05-16T07:07:17.305Z","repository":{"id":37359603,"uuid":"118914793","full_name":"poljar/weechat-matrix","owner":"poljar","description":"Weechat Matrix protocol script written in python","archived":false,"fork":false,"pushed_at":"2023-07-23T09:41:39.000Z","size":940,"stargazers_count":972,"open_issues_count":132,"forks_count":126,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-05-09T04:17:50.730Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/poljar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-01-25T13:15:21.000Z","updated_at":"2025-04-30T18:02:19.000Z","dependencies_parsed_at":"2024-01-15T05:09:37.338Z","dependency_job_id":"467519e7-855a-4be6-9860-fba07b915bf0","html_url":"https://github.com/poljar/weechat-matrix","commit_stats":{"total_commits":775,"total_committers":52,"mean_commits":"14.903846153846153","dds":"0.20903225806451609","last_synced_commit":"989708d1fa8fcee6d5bbb4c19a7d66f14d84fd5b"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fweechat-matrix","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fweechat-matrix/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fweechat-matrix/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/poljar%2Fweechat-matrix/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/poljar","download_url":"https://codeload.github.com/poljar/weechat-matrix/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254485065,"owners_count":22078767,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T15:00:54.161Z","updated_at":"2025-05-16T07:07:12.226Z","avatar_url":"https://github.com/poljar.png","language":"Python","funding_links":[],"categories":["Python","Clients","\u003ca name=\"chat\"\u003e\u003c/a\u003eChat and instant messaging"],"sub_categories":["CLI"],"readme":"[![Build Status](https://img.shields.io/travis/poljar/weechat-matrix.svg?style=flat-square)](https://travis-ci.org/poljar/weechat-matrix)\n[![#weechat-matrix](https://img.shields.io/badge/matrix-%23weechat--matrix:termina.org.uk-blue.svg?style=flat-square)](https://matrix.to/#/!twcBhHVdZlQWuuxBhN:termina.org.uk?via=termina.org.uk\u0026via=matrix.org)\n[![license](https://img.shields.io/badge/license-ISC-blue.svg?style=flat-square)](https://github.com/poljar/weechat-matrix/blob/master/LICENSE)\n\n# What is Weechat-Matrix?\n\n[Weechat](https://weechat.org/) is an extensible chat client.\n\n[Matrix](https://matrix.org/blog/home) is an open network for secure,\ndecentralized communication.\n\n[weechat-matrix](https://github.com/poljar/weechat-matrix/) is a Python script\nfor Weechat that lets Weechat communicate over the Matrix protocol.\n\n# Project Status\n\nweechat-matrix is stable and quite usable as a daily driver. It already\nsupports large parts of the Matrix protocol, including end-to-end encryption\n(though some features like cross-signing and session unwedging are\nunimplemented).\n\nHowever, due to some inherent limitations of Weechat *scripts*, development has\nmoved to [weechat-matrix-rs](https://github.com/poljar/weechat-matrix-rs),\na Weechat *plugin* written in Rust. As such, weechat-matrix is in maintenance\nmode and will likely not be receiving substantial new features. PRs are still\naccepted and welcome.\n\n# Installation\n\n## Arch Linux\n\nPackaged as `community/weechat-matrix`.\n\n    pacman -S weechat-matrix\n\n## Alpine Linux\n\n    apk add weechat-matrix\n\nThen follow the instructions printed during installation to make the script\navailable to weechat.\n\n## Other platforms\n\n1. Install libolm 3.1+\n\n    - Debian 11+ (testing/sid) or Ubuntu 19.10+ install libolm-dev\n\n    - FreeBSD `pkg install olm`\n\n    - macOS `brew install libolm`\n\n    - Failing any of the above see https://gitlab.matrix.org/matrix-org/olm\n      for instructions about building it from sources\n\n2. Clone the repo and install dependencies\n    ```\n    git clone https://github.com/poljar/weechat-matrix.git\n    cd weechat-matrix\n    pip install --user -r requirements.txt\n    ```\n\n3. As your regular user, just run: `make install` in this repository directory.\n\n    This installs the main python file (`main.py`) into\n    `~/.weechat/python/` (renamed to `matrix.py`) along with the other\n    python files it needs (from the `matrix` subdir).\n\n    Note that weechat only supports Python2 OR Python3, and that setting is\n    determined at the time that Weechat is compiled.  Weechat-Matrix can work with\n    either Python2 or Python3, but when you install dependencies you will have to\n    take into account which version of Python your Weechat was built to use.\n\n    The minimal supported python2 version is 2.7.10.\n\n    The minimal supported python3 version is 3.5.4 or 3.6.1.\n\n    To check the python version that weechat is using, run:\n\n       /python version\n\n## Using virtualenv\nIf you want to install dependencies inside a virtualenv, rather than\nglobally for your system or user, you can use a virtualenv.\nWeechat-Matrix will automatically use any virtualenv it finds in a\ndirectory called `venv` next to its main Python file (after resolving\nsymlinks). Typically, this means `~/.weechat/python/venv`.\n\nTo create such a virtualenv, you can use something like below. This only\nneeds to happen once:\n\n```\nvirtualenv ~/.weechat/python/venv\n```\n\nThen, activate the virtualenv:\n\n```\n. ~/.weechat/python/venv/bin/activate\n```\n\nThis needs to be done whenever you want to install packages inside the\nvirtualenv (so before running the `pip install` command documented\nabove.\n\n\nOnce the virtualenv is prepared in the right location, Weechat-Matrix\nwill automatically activate it when the script is loaded. This should\nnot affect other script, which seem to have a separate Python\nenvironment.\n\nNote that this only supports virtualenv tools that support the\n[`activate_this.py` way of\nactivation](https://virtualenv.pypa.io/en/latest/userguide/#using-virtualenv-without-bin-python).\nThis includes the `virtualenv` command, but excludes pyvenv and the\nPython3 `venv` module. In particular, this works if (for a typical\ninstallation of `matrix.py`) the file\n`~/.weechat/python/venv/bin/activate_this.py` exists.\n\n## Run from git directly\n\nRather than copying files into `~/.weechat` (step 3 above), it is also\npossible to run from a git checkout directly using symlinks.\n\nFor this, you need two symlinks:\n\n```\nln -s /path/to/weechat-matrix/main.py ~/.weechat/python/matrix.py\nln -s /path/to/weechat-matrix/matrix ~/.weechat/python/matrix\n```\n\nThis first link is the main python file, that can be loaded using\n`/script load matrix.py`. The second link is to the directory with extra\npython files used by the main script. This directory must be linked as\n`~/.weechat/python/matrix` so it ends up in the python library path and\nits files can be imported using e.g. `import matrix` from the main python\nfile.\n\nNote that these symlinks are essentially the same as the files that\nwould have been copied using `make install`.\n\n## Uploading files\n\nUploads are done using a helper script, which is found under\n[contrib/matrix_upload](https://github.com/poljar/weechat-matrix/blob/master/contrib/matrix_upload.py).\nWe recommend you install this under your `PATH` as `matrix_upload` (without the `.py` suffix).\nUploads can be done from Weechat with: `/upload \u003cfile\u003e`.\n\n## Downloading encrypted files\n\nEncrypted files are displayed as an `emxc://` URI which cannot be directly\nopened. They can be opened in two different ways:\n\n- **In the CLI** by running the\n[contrib/matrix_decrypt](https://github.com/poljar/weechat-matrix/blob/master/contrib/matrix_decrypt.py)\nhelper script.\n\n- **In the browser** by using\n  [matrix-decryptapp](https://github.com/seirl/matrix-decryptapp). This is a\n  static website which cannot see your data, all the decryption happens\n  on the client side. You can either host it yourself or directly use the\n  instance hosted on `seirl.github.io`. This weechat trigger will convert all\n  your `emxc://` URLs into clickable https links:\n\n  ```\n  /trigger addreplace emxc_decrypt modifier weechat_print \"\" \";($|[^\\w/#:\\[])(emxc://([^ ]+));${re:1}https://seirl.github.io/matrix-decryptapp/#${re:2};\"\n  ```\n\n# Configuration\n\nConfiguration is completed primarily through the Weechat interface.  First start Weechat, and then issue the following commands:\n\n1. Start by loading the Weechat-Matrix script:\n\n       /script load matrix.py\n\n2. Now set your username and password:\n\n       /set matrix.server.matrix_org.username johndoe\n       /set matrix.server.matrix_org.password jd_is_awesome\n\n3. Now try to connect:\n\n       /matrix connect matrix_org\n\n4. Automatically load the script\n\n       $ ln -s ../matrix.py ~/.weechat/python/autoload\n\n5. Automatically connect to the server\n\n       /set matrix.server.matrix_org.autoconnect on\n\n6. If everything works, save the configuration\n\n       /save\n\n## For using a custom (not matrix.org) matrix server:\n\n1. Add your custom server to the script:\n\n       /matrix server add myserver myserver.org\n\n1. Add the appropriate credentials\n\n       /set matrix.server.myserver.username johndoe\n       /set matrix.server.myserver.password jd_is_awesome\n\n1. If everything works, save the configuration\n\n       /save\n\n## Single sign-on:\n\nSingle sign-on is supported using a helper script, the script found under\n[contrib/matrix_sso_helper](https://github.com/poljar/weechat-matrix/blob/master/contrib/matrix_sso_helper.py)\nshould be installed under your `PATH` as `matrix_sso_helper` (without the `.py` suffix).\n\nFor single sign-on to be the preferred leave the servers username and password\nempty.\n\nAfter connecting a URL will be presented which needs to be used to perform the\nsign on. Please note that the helper script spawns a HTTP server which waits for\nthe sign-on token to be passed back. This makes it necessary to do the sign on\non the same host as Weechat.\n\nA hsignal is sent out when the SSO helper spawns as well, the name of the\nhsignal is `matrix_sso_login` and it will contain the name of the server in the\n`server` variable and the full URL that can be used to log in in the `url`\nvariable.\n\nTo open the login URL automatically in a browser a trigger can be added:\n\n        /trigger add sso_browser hsignal matrix_sso_login \"\" \"\" \"/exec -bg firefox ${url}\"\n\nIf signing on on the same host as Weechat is undesirable the listening port of\nthe SSO helper should be set to a static value using the\n`sso_helper_listening_port` setting:\n\n       /set matrix.server.myserver.sso_helper_listening_port 8443\n\nAfter setting the listening port the same port on the local machine can be\nforwarded using ssh to the remote host:\n\n        ssh -L 8443:localhost:8443 example.org\n\nThis forwards the local port 8443 to the localhost:8443 address on example.org.\nNote that it is necessary to forward the port to the localhost address on the\nremote host because the helper only listens on localhost.\n\n## Bar items\n\nThere are two bar items provided by this script:\n\n1. `matrix_typing_notice` - shows the currently typing users\n\n1. `matrix_modes` - shows room and server info (encryption status of the room,\n   server connection status)\n\nThey can be added to the weechat status bar as usual:\n       /set weechat.bar.status.items\n\nThe `matrix_modes` bar item is replicated in the already used `buffer_modes` bar\nitem.\n\n## Typing notifications and read receipts\n\nThe sending of typing notifications and read receipts can be temporarily\ndisabled for a given room via the `/room` command. They can also be permanently\nconfigured using standard weechat conditions settings with the following\nsettings:\n\n1. `matrix.network.read_markers_conditions`\n1. `matrix.network.typing_notice_conditions`\n\n## Cursor bindings\n\nWhile you can reply on a matrix message using the `/reply-matrix` command (see\nits help in weechat), weechat-matrix also adds a binding in `/cursor` mode to\neasily reply to a particular message. This mode can be triggered either by\nrunning `/cursor`, or by middle-clicking somewhere on the screen. See weechat's\nhelp for `/cursor`.\n\nThe default binding is:\n\n    /key bindctxt cursor @chat(python.matrix.*):r hsignal:matrix_cursor_reply\n\nThis means that you can reply to a message in a Matrix buffer using the middle\nmouse button, then `r`.\n\nThis binding is automatically set when the script is loaded and there is no\nsuch binding yet. If you want to use a different key than `r`, you can execute\nthe above command with a different key in place of `r`. To use modifier keys\nlike control and alt, use alt-k, then your wanted binding key combo, to enter\nweechat's representation of that key combo in the input bar.\n\n## Navigating room buffers using go.py\n\nIf you try to use the `go.py` script to navigate buffers created by\nweechat-matrix, `go.py` will by default use the full buffer name which does not\ncontain a human-readable room display name but only the Matrix room ID. This is\nnecessary so that the logger file is able to produce unique, permanent\nfilenames for a room.\n\nHowever, buffers also have human-readable short names. To make `go.py` use the\nshort names for navigation, you can run the following command:\n\n```\n/set plugins.var.python.go.short_name \"on\"\n```\n\nAs an alternative, you can also force weechat-matrix to use human-readable\nnames as the full buffer names by running\n\n```\n/set matrix.look.human_buffer_names on\n```\n\nBeware that you will then also need to adjust your logger setup to prevent room\nname conflicts from causing logger file conflicts.\n\n# Helpful Commands\n\n`/help matrix` will print information about the `/matrix` command.\n\n`/help olm` will print information about the `/olm` command that is used for\ndevice verification.\n\n`/matrix help [command]` will print information for subcommands, such as `/matrix help server`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoljar%2Fweechat-matrix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpoljar%2Fweechat-matrix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpoljar%2Fweechat-matrix/lists"}