Cat Puppet Bridge

A modern bridge from IRC to Discord which uses "puppets" (fake IRC Users controlled by the bridge) to make integration more seamless. The name comes from the UNIX command cat which concatenates data and outputs it to the screen, or in this case we are cating our data out to a puppet to bridge it. Hence the name Cat Puppet Bridge.

Features

• Uses WebIRC for enhanced security (makes it harder for people to impersonate a bot)
• Allows sending Direct/Private Messages between Discord and IRC Users
• IRC Puppets of Discord users
  • Puppets only join linked channels that they have permissions to be in (we may be the only bridge that does this!)
  • Puppets will quit when the user leaves the discord Guild
  • Puppets will set AFK when their Discord user is away or offline, and UNAFK when they are back
• Discord communication uses webhooks
  • Webhooks set the name to match their IRC user
  • If the IRC username matches a Discord username it will automatically use the avatar from their Discord account
  • Random avatars are generated by https://robohash.org/ (thank you robohash!)

Python Versions

Current Python Compatibility (main/latest)

Python Version	Test Status
3.10
3.11
3.12
3.13
3.14

Previous Release Python Compatibility

Release	3.10	3.11	3.12	3.13	3.14
>= 1.1.3	✔️	✔️	✔️	✔️	✔️
<= 1.1.2	✔️	✔️	❌	❌	❌

Installing

Prerequisites

• An IRC Server to connect to
• A discord Guild you have administrative permissions on

Install From Source

• Clone the source git clone https://github.com/e-lisa/CatPuppetBridge
• Check out the latest tag, or a release of your choice (eg v1.1.3) git checkout latest

Installing with a Virtual Environment

• Install CatPuppetBridge with a Virtual Environment sudo make install-venv
• Configure the bridge in /etc/catbridge.ini with the editor of your choice
• Start the bridge sudo systemctl start catpuppetbridge

Developing

Prerequisites

• A Discord Server to invite the bot to
• Python 3.x

IRC Server for Testing

For testing we recommend using irc.server implementation for testing.

• Activate the virtualenv: source .venv/bin/activate
• Start the irc server: python -m 'irc.server'

Create a Discord Bot

• Navigate to https://discord.com/developers/applications/
• Create a new application by clicking New Application
• Obtain your token by clicking Bot then Reset Token then finally Copy to copy it to your clipboard
• Save this token to add to the catpuppet.ini file detailed below (if you lose this, you will have to regenerate it)

Invite bot to your Discord Server

• Navigate to https://discord.com/developers/applications/
• Click the bot you created in the previous step
• Click OAuth2
• Click Add Redirect
• Any URL can be added, if not sure what to use just use our GitHub https://github.com/e-lisa/CatPuppetBridge
• Under OAuth2 URL Generator check the bot box
• Under BOT PERMISSIONS check:
  • Send Messages
  • Add Reactions
  • Read Message History
  • Manage Webhooks
• Under GENERATED URL click Copy to copy the URL
• Navigate to the URL you have copied to invite the bot to your guild

Building

• Copy the default configuration: cp catbridge.ini.default catbridge.ini
• Open catbridge.ini with your editor of choice and add your:
  • Token (generated in the Create a Discord Bot step above)
• Create a virtualenv virtualenv .venv
• Activate the virtualenv source .venv/bin/activate
• Install dependencies into the virtualenv pip install requirements/prod-requirements.txt
• Run the bridge: python main.py

Contributing

• Issue Tracker: https://github.com/e-lisa/CatPuppetBridge/issues
• IRC: OFTC #catpuppetbridge

License

• GPLv3: https://www.gnu.org/licenses/gpl-3.0.en.html#license-text