Proxier bot for Matrix

July 18, 2026 | 4 min read

Started working on a proxy bot for Matrix a bit ago, similar to PluralKit! Still a work in progress, I'm mostly putting this up as a command reference for friends who are using(/testing) the bot.

(Proxy bots, for those who don't know, are chatroom bots - like a Discord bot - that will re-send a user's message with a "mock" account. People also use them for roleplay, but a lot of plural folks use them to keep track of who is saying what without having to sign off on every individual message and without having to make multiple chat accounts.)

Also wrote it with the terms "house" and "household" instead of "system" for clarity (and, honestly, as a nod to plural history - that word has been used since the '90s)!

Commands

(click to see list of commands)

Help
- Shows help info
House
- New
  - Create/register new household
  - house new [NAME]
- Rename
  - Rename current household
  - NOT IMPLEMENTED YET
- Tag
  - Set house tag to be appended after each member's name when they proxy
  - house tag [TAG]
- Color
  - Set house color to be used for house tag
  - house color [COLOR_HEXCODE]
- Roster
  - View a list of household members
  - NOT IMPLEMENTED YET
- Delete
  - Delete registered household
  - NOT IMPLEMENTED YET
    - Needs to prompt for a confirmation before irreversibly deleting data
Member
- New
  - Add new member
  - member new [NAME]
- Name
  - Change member name
  - member name [OLDNAME] [NEWNAME]
- Displayname
  - Change member display name
  - member displayname [NAME] [DISPLAYNAME]
- Avatar
  - Change avatar to a given image from URL
  - member avatar [NAME] [IMG_URL]
- Proxy
  - Change member proxy
  - member proxy [NAME] [PROXYTAGS]
- Color
  - Change member color
  - member color [NAME] [COLOR_HEXCODE]
- PK
  - Update or add a member's associated pluralkit ID, either for record-keeping or (eventually) possibly for edit operations
  - NOT IMPLEMENTED YET
- Delete
  - Delete a member
  - NOT IMPLEMENTED YET
Autoproxy
- Works a little differently than with Discord. Autoproxy can be globally enabled or disabled, then set to either LATCH or STATIC on a per-room basis.
- Disable
  - Globally disable autoproxying. Also clears out all current autoproxies set in any room.
  - autoproxy disable
- Enable
  - Globally enable autoproxying. Does not create an autoproxy session, however; that has to be set per-room.
  - autoproxy enable
- Off
  - Turn autoproxy off for the room it was run in.
  - autoproxy off
- Latch
  - Set autoproxy to LATCH for the room it was run in.
  - autoproxy latch
- Static
  - Set autoproxy to STATIC for the room it was run in. That will set a specific member to always autoproxy in that room, even if other members are proxying too.
  - autoproxy static MEMBERNAME
- Timeout
  - Set LATCH autoproxy timeout in HOURS (fractional/decimal hours permitted) (does not affect STATIC).
  - autoproxy timeout HOURS
- Backslash
  - \ makes a single message not autoproxy
  - \\ clears the autoproxy session in that room (essentially turns autoproxy off in that room until someone else proxies)
Pluralkit
- DON'T RUN THIS MULTIPLE TIMES RIGHT NOW UNLESS YOU KNOW WHAT YOU'RE DOING, IT WILL JUST DUPLICATE EVERY MEMBER
- Imports members' names, display names, avatar, colors, proxy tag, and 5- or 6-letter PKID
- pluralkit TOKEN
- (tokens are not saved by the bot; would suggest running this in a private room with the bot, since pluralkit tokens are like your password)

Notes and To-Do's

Would love to be able to use PK's API to edit/add/etc. members/households/systems from Matrix? Would probably require storing user tokens, however. Hmmm.
Eventually allow autoproxies to be set either globally or per-space...? Can we do that with Matrix spaces? Allow setting autoproxy for a list of rooms?
Not sure what to do about old unused icons.
- Synapse has an API endpoint for deleting media, but Conduit doesn't seem to, so it's up to homeservers, not even bot admins, to prune out media. Not sure I like that. Hm.
How to handle repeated imports!!! NOT IMPLEMENTED YET, running pluralkit import multiple times will just duplicate members
- Record PKID and either skip or update existing member if member with same PKID already exists?
Make a Setup function where a user can determine certain variables on startup, such as a debug room ID to direct error messages to, bot tokens and names, prefixes, and admin matrixID