Entering the Matrix with Hookshot / Feb 2025

We've been happy users of Matrix for our group communications in the EEG. Today we've been bringing in more members of the wider group to using it instead of Slack. As part of that, I've set up a cool bot called Hookshot which allows Matrix to be connected to external services such as GitHub and Atom/RSS feeds. This is a test post to demonstrate to the members of the EEG how Matrix and Atom work!

The basic idea behind Hookshot is to provide a bridging service to communications rooms hosted on Matrix, in such a way that it can exert administrative control over a room to intercept requests for services (such as adding an Atom feed).

The setup for Hookshot can be a little involved as there are lots of encryption keys flying around. In a nutshell, I have a Docker container running it with a Yaml config of this nature:

bridge:
  domain: recoil.org
  url: http://synapse:8008
  port: 9993
  bindAddress: 0.0.0.0
passFile:
  /data/hookshot.pem
experimentalEncryption:
  storagePath: /state
experimental_features:
  msc3202_device_masquerading: true
  msc3202_transaction_extensions: true
  msc2409_to_device_messages_enabled: true
logging:
  level: debug
  colorize: true
  json: false
  timestampFormat: HH:mm:ss:SSS

This gives me a healthy amount of debug logging, and uses my personal Matrix server at recoil.org as the "home" for the bot. Ryan Gibb set up our EEG Matrix server completely separately over in a VM in the Computer Lab, at eeg.cl.cam.ac.uk. It's pretty cool that Matrix allows for this sort of decentralised communucation pretty seamlessly!

After this worked and was tested, I now have an active bot user on the Matrix (in this case, it's llama:recoil.org. I then configured GitHub on Hookshot so that the bot can monitor GitHub via its API.

github:
  auth:
    id: 861482
    privateKeyFile: /data/github-key.pem
  webhook:
    secret: <secret>
  oauth:
    client_id: <client-id>
    client_secret: <client-secret>
    redirect_uri: https://recoil.org/hookshot/oauth/
  defaultOptions:
    showIssueRoomLink: false
    hotlinkIssues:
      prefix: "#"

This bit of Yaml takes some configuring via the GitHub OAuth API to get the client-id and secrets. Once that's done, the bot can then be instructed to monitor certain repositories just by issing some commands from within Matrix!

After this, the bot can be configured for a variety of other service. For instance it can monitor Atom feeds to keep track of what the whole group is writing. For this, it's as simple as:

• Invite the bot to the room and give it admin privileges
• Write a message !hookshot feed https://anil.recoil.org/news.xml (as an example for my feed)
• The bot will start monitoring it and post every five minutes by default

Hookshot supports a variety of other services to bridge to as well, including webhooks for arbitrary services. One of the most fun student projects I've supervised recently is "Decentralised Capability-based Code Collaboration using Matrix" in which Samuel Wedgwood built Git-patches-over-Matrix. If anyone wants to pick up on that and build a "real" version, perhaps we could use this for peer-to-peer coding! It might work really well with coding copilots, as they have a chat based interface anyway...