Reading the room

The script uses the plain client-server API with httpx. It fetches the last 100 events of the room with /messages?dir=b, so the newest event comes first. Then it collects the bot's checkmarks and walks back through my messages until it hits one that is already acked:

acked = {
    ev["content"]["m.relates_to"]["event_id"]
    for ev in events
    if ev["type"] == "m.reaction" and ev["sender"] == BOT
}

new = []
for ev in events:
    if ev["type"] != "m.room.message" or ev["sender"] != OWNER:
        continue
    if ev["event_id"] in acked:
        break  # everything older is acked too
    new.append(ev)

The script skips edits, otherwise fixing a typo in Matrix would add a new entry.

The inbox file

The first line of a message becomes the headline, every further line becomes the body. Entries are grouped by day, newest day on top and newest entry on top within a day:

#+STARTUP: showeverything
#+TITLE: Matrix inbox

* matrix inbox entries

** 2026-10-31

*** TODO prepare a draft blog post for the matrix org bot
*** TODO check the airpressure on the cube29

Ack only after the push

The order matters: if the bot reacts before the push and the push fails, the message is acked but the entry is lost with the runner. So the script has two modes, matrix-inbox.py to add the messages and matrix-inbox.py ack to react, and the git part stays in the workflow between them:

steps:
  - uses: actions/checkout@v7
    with:
      token: ${{ secrets.GITHUB_TOKEN }}
  - name: Install uv
    uses: https://github.com/astral-sh/setup-uv@v6
  - name: Add new messages to inbox
    run: uv run matrix-inbox.py
  - name: Commit and push
    run: |
      git config user.name "Automated"
      git config user.email "actions@forgejo.local"
      git remote set-url origin https://oauth2:${{ secrets.GITHUB_TOKEN }}@forgejo.example.com/${{ github.repository }}
      git add matrix-inbox.org
      git diff --staged --quiet || git commit -m "matrix inbox - $(TZ=Europe/Berlin date +'%Y-%m-%d %H:%M')"
      git push
  - name: Ack messages
    run: uv run matrix-inbox.py ack

The event ids of the added messages are handed from the first uv run matrix-inbox to the second one via a small file in $RUNNER_TEMP.

Homeassistant

The Hermes agent already has a Homeassistant token in its .env, so the script reads HASS_URL and HASS_TOKEN from there. Two REST API calls are enough:

class HomeAssistant:
    def __init__(self, url, token):
        self.url = url.rstrip("/")
        self.headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}

    def state(self, entity_id):
        return fetch_json(f"{self.url}/api/states/{entity_id}", headers=self.headers)

    def forecast(self, kind):
        resp = fetch_json(
            f"{self.url}/api/services/weather/get_forecasts?return_response",
            data={"entity_id": WEATHER_ENTITY, "type": kind},
            headers=self.headers,
        )
        return resp["service_response"][WEATHER_ENTITY]["forecast"]

The waste sensors are the ones from Homeassistant Tracking Waste Collection Dates. Their state is a date, so the script only compares it with today and tomorrow. The car battery is a plain state too (sensor.r5_battery and sensor.r5_battery_autonomy for the range).

The weather forecast comes from the weather.get_forecasts service. The script calls it twice: daily for the min/max temperature and hourly for the rain. Consecutive hours with rain are grouped, so the message shows 22-24 Uhr 0.6 mm instead of a list of single hours.

Library opening hours

The opening hours of my local library branch are on its page on the Stadtbibliothek website. The hours are plain HTML:

<h2>Öffnungszeiten</h2><strong>Dienstag</strong> 14:00 - 19:00 Uhr
<br><strong>Mittwoch</strong> 10:00 - 15:00 Uhr

A regular expression on the block after the heading returns a dict of weekday and hours. The hours rarely change, so fetching them every morning is a bit much and I may cache them later.

VfB home games

OpenLigaDB has an endpoint that returns the matches of a team for a number of weeks in the past and the future. VfB Stuttgart has the team id 16 and the result contains Bundesliga, DFB-Pokal and Champions League matches. A home game is a match where VfB is team1:

def section_vfb(today):
    matches = fetch_json(f"https://api.openligadb.de/getmatchesbyteamid/{VFB_TEAM_ID}/1/1")
    home = [
        m for m in matches
        if m["team1"]["teamId"] == VFB_TEAM_ID and to_local(m["matchDateTimeUTC"]).date() == today
    ]
    return f"⚽ **VfB {'' if home else 'kein '}Heimspiel heute!**"

S-Bahn and SSB

The VVS has an EFA endpoint (XML_ADDINFO_REQUEST) that returns all current info messages as JSON. On the day I tried it there were 414 messages, most of them with AlertCause: roadworks. After removing roadworks and broken elevators, the script keeps only messages for S-Bahn, U-Bahn and SSB lines that are active today. To filter out long planned changes, a message has to be published at most one day before it starts. This is a heuristic and I will see if it is too noisy over the next weeks.

Sending the message

Hermes already has a CLI command for this, hermes send, which reuses the credentials of the agent:

subprocess.run([HERMES, "send", "--to", MATRIX_TARGET, "--quiet", "--file", "-"],
               input=summary, text=True, check=True)