Skip to content

netresearch/matrix-skill / skills/matrix-administration

matrix-administration

Unverified

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.

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

uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-fetch-rooms.py [--server :example.com]
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-rate-rooms.py --space '!home:srv' [--language de]
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-graph.py --space '!home:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-biggest-rooms.py [-n 10]

uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-join-room.py    '!room:srv' '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-make-admin.py   '!room:srv' '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-add-to-space.py '!room:srv' '!space:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-migrate-room.py '!room:srv' '@admin:srv' '!space:srv'   # DESTRUCTIVE, asks first

uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-deactivate-user.py   '@user:srv'   # DESTRUCTIVE
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-user-rooms.py        '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-user-admin-rooms.py  '@user:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-room-member-flow.py  '!room:srv'
uv run ${CLAUDE_SKILL_DIR}/scripts/synapse-search.py            '!room:srv' '@bot:srv' deploy

Scripts

ScriptPurpose
synapse-fetch-rooms.pySnapshot all rooms + state → rooms.json
synapse-rate-rooms.pyHealth checks (EN/DE) on rooms.json
synapse-graph.pyRender rooms.json → Graphviz .dot + .svg
synapse-biggest-rooms.pyTop-N rooms by DB size
synapse-join-room.pyForce-join a user
synapse-make-admin.pyPromote to PL 100
synapse-add-to-space.pySend m.space.child
synapse-migrate-room.pyAdd to space + restrict + encrypt
synapse-deactivate-user.pyDestructive deactivation (--erase for GDPR)
synapse-user-admin-rooms.pyLocal: rooms where user is PL 100
synapse-user-rooms.pyLocal: rooms a user belongs to
synapse-room-member-flow.pyJoin/leave timeline
synapse-search.pyUnencrypted history search

Setup

~/.config/matrix/config.json (respects $XDG_CONFIG_HOME):

{
  "homeserver": "https://matrix.example.com",
  "admin_token": "syt_admin_…",
  "room_filter": ":example.com",
  "default_space_id": "!home:example.com",
  "home_space_ids": ["!home:example.com"]
}

homeserver and either admin_token or access_token (server-admin) are required. The other fields are optional. To keep the token out of this file, set admin_token_file to a file holding it (relative paths resolve against the config directory) or export MATRIX_ADMIN_TOKEN; the environment wins over the file, the file over the inline value. Env fallbacks: MATRIX_USER_ID, MATRIX_SPACE_ID, LANGUAGE=en|de, NO_COLOR.

Safety

The token is server-admin. Read references/safety-guide.md before any destructive op.

  • synapse-deactivate-user.py is irreversible.
  • synapse-migrate-room.py enables encryption (one-way) and restricts joins; it prints the plan and asks before the first write (--yes skips, and is required without a terminal). Power-level changes restored on exit including Ctrl-C.
  • synapse-make-admin.py raises PL 100 permanently.
  • synapse-search.py cannot read E2EE — empty ≠ no messages.
  • rooms.json exposes user IDs; never commit it.

References

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 467kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 193kUpdated Claude CodeCodexVerifiedInstall