IRC nick batch renamer tool for Matrix

This script renames IRC nicks of puppeting bridge users to more sane counterparts. The design goal is to make IRC users' life more pleasant by the following ways:

• Nick list looks good. It is easier to see who you are actually talking to. For example umlaut characters and other non-ASCII characters in nicks are not just silently dropped but best effort is done to transliterate them to ASCII.
• It's easy to see if you can PM to somebody. Unlike native Matrix users which can talk to IRC users in private, the puppet users cannot handle that. When you see ^something in the nick, you are warned.
• Puppet users do not pollute IRC nickspace. If a Telegram puppet is having a nick Joe, he wouldn't steal nick Joe on IRC but occupies Joe|tinstead.

The following puppeting bridges are tested to work with this script:

• Mautrix-Telegram
• Mautrix-Whatsapp
• Matrix Discord Bridge
• Matrix-appservice-slack

Installation

Copy examples/config.yml from example directory to the parent directory and edit it to your needs. You need to change the following global setting:

• server: Set to your homeserver URL (including port).

And for every puppeting bridge you need the following:

• token: Set to as_token of your puppeting brudge. Copy it from your appservice's config file.
• mxid: Appservice bot MXID. Used to find the channels where puppets reside.
• regex: Pattern to match to user MXIDs to see if it's a puppet.
• irc_suffix: String to add to the end of the nickname (such as |t)

Python requirements

Set up virtualenv or install dependencies globally. This script is so simple so I suggest installing dependencies from APT.

In Ubuntu and Debian, run:

sudo apt install python3-yaml python3-unidecode

Make it automatic

Copy files examples/matrix-irc-nick.service and examples/matrix-irc-nick.timer to /etc/systemd/system/. Update service path and user names in service file and randomize timer execution time in timer file to somewhere at night time so all servers using this script are not creating the peak at the same time.

Try once:

sudo systemctl daemon-reload
sudo systemctl start --no-block matrix-irc-nick.service
sudo journalctl -fu matrix-irc-nick.service

If it executes without errors, enable the timer to make it recurring:

sudo systemctl enable matrix-irc-nick.timer
sudo systemctl start matrix-irc-nick.timer

Adding new supported IRC networks

The script can rename nicknames in any network which supports appservice !nick command. Only requirements are bridge server name, its room alias format and appservice matrix id.

Add those to config.yaml and please submit pull request to make them mainstream. The required parameters can be found from List of bridged IRC networks.

If you plan to run this

If you plan to run this, it will compete with other matrix-irc-nick instances on the same IRC network and leads to messy behaviour on both sides. So please coordinate the usage somehow with others. On private IRC networks there is no problem.

Hacklab Finland used this script to rename IRCNet puppets from 2019 to September 2023. The sunset of renaming happened because they've shifted to using Heisenbridge instead of matrix-appservice-irc because the latter was beyond repair.

Maintainer

The first version was written by vurpo and has been refactored by Zouppen. Maintained by Hacklab.fi community and was actively used on Hacklab.fi's Matrix home server until September 2023.