matrix-administration

name	matrix-administration
description	Use when administering a Synapse / Matrix homeserver — list or snapshot all rooms, rate room health (public, unencrypted, orphaned), render a Graphviz map of the room/space tree, force-join users, promote room admins, harden rooms (add-to-space + restrict + encrypt), deactivate Matrix users (with GDPR erase), find biggest rooms by DB size, audit where a user is admin or member, replay join/leave timelines, or search unencrypted history. Trigger on any '/_synapse/admin', server-wide room operation, Matrix user offboarding, or anything requiring a homeserver-admin token — even without 'admin API' in the prompt. Companion to matrix-communication.
license	(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0
compatibility	python3 (stdlib only) + a Matrix access token belonging to a Synapse server-admin user. Optional: graphviz `dot` for SVG. Synapse 1.x with admin API enabled.
metadata	{"author":"Netresearch DTT GmbH","version":"3.1.1","repository":"https://github.com/netresearch/matrix-skill"}
allowed-tools	Bash(python3:*) Bash(uv:*) Bash(dot:*) Read Write

Matrix Administration

Stdlib-only Python wrappers around the Synapse Admin API and the Client-Server API. Reads ~/.config/matrix/config.json (the same file matrix-communication uses).

Quick Reference

S=skills/matrix-administration/scripts

python3 $S/synapse-fetch-rooms.py [--server :example.com]
python3 $S/synapse-rate-rooms.py --space '!home:srv' [--language de]
python3 $S/synapse-graph.py --space '!home:srv'
python3 $S/synapse-biggest-rooms.py [-n 10]

python3 $S/synapse-join-room.py    '!room:srv' '@user:srv'
python3 $S/synapse-make-admin.py   '!room:srv' '@user:srv'
python3 $S/synapse-add-to-space.py '!room:srv' '!space:srv'
python3 $S/synapse-migrate-room.py '!room:srv' '@admin:srv' '!space:srv'   # DESTRUCTIVE, asks first

python3 $S/synapse-deactivate-user.py   '@user:srv'   # DESTRUCTIVE
python3 $S/synapse-user-rooms.py        '@user:srv'
python3 $S/synapse-user-admin-rooms.py  '@user:srv'
python3 $S/synapse-room-member-flow.py  '!room:srv'
python3 $S/synapse-search.py            '!room:srv' '@bot:srv' deploy

Scripts

Script	Purpose
synapse-fetch-rooms.py	Snapshot all rooms + state → rooms.json