netresearch/matrix-skill / skills/matrix-administration
matrix-administration
VerifiedUse 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.
README.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Matrix Administration
Operate on a Synapse Matrix homeserver via the [Synapse Admin API](https://element-hq.github.io/synapse/latest/usage/administration/admin_api/index.html). Companion to the **matrix-communication** skill in this repo.
## Features
- **Snapshot every room** — `rooms.json` of every visible room and its state
- **Health rating** — flag public, unencrypted, or orphaned-from-spaces rooms (English + German)
- **Graphviz map** — colour-coded SVG of the homeserver's room/space tree
- **Force-join, promote admin, link to space** — point-and-shoot moderation tools
- **Hardening pipeline** — `synapse-migrate-room.py` adds a room to a space, restricts joins, enables encryption, and restores power levels
- **Deactivate users** — destructive, with optional GDPR `--erase`
- **Inspection** — list a user's admin/membership rooms, replay join/leave timelines, search unencrypted history
- **Stdlib-only Python** — no third-party dependencies
## Installation
### Via the Netresearch marketplace (recommended)
```bash
/plugin marketplace add netresearch/claude-code-marketplace
```
Then `/install-plugin netresearch/matrix-skill`. Both `matrix-communication` and `matrix-administration` ship in the same plugin.
### Via release download
Grab the [latest release](https://github.com/netresearch/matrix-skill/releases/latest) and extract to `~/.claude/skills/matrix-administration/`.
## Configuration
`~/.config/matrix/config.json`:
```json
{
"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"]
}
```
The token must belong to a user with **server-admin** rights (`user_type: 'admin'` on the user object). `room_filter`, `default_space_id`, and `home_space_ids` are optional — none of them ship pre-set.
## Usage
The skill triggers on Synapse-admin tasks: "list all rooms on the homeserver", "rate room health", "deactivate user `@bob`", "find rooms with no admin in our org space".
### Example prompts
```
"Snapshot every room on matrix.example.com and rate them in German"
"Render an SVG of the room tree, treating !home:example.com as our home space"
"Deactivate @leaver:example.com and erase their messages"
"Where is @alice:example.com a room admin? Highlight rooms with no other admins."
"Make !room:example.com private, add it to !home:example.com, and enable encryption"
```
## Structure
```
matrix-administration/
├── SKILL.md # AI instructions
├── README.md # this file
├── scripts/
│ ├── _lib/ # stdlib-only shared helpers
│ ├── synapse-fetch-rooms.py
│ ├── synapse-rate-rooms.py
│ ├── synapse-graph.py
│ ├── synapse-biggest-rooms.py
│ ├── synapse-join-room.py
│ ├── synapse-make-admin.py
│ ├── synapse-add-to-space.py
│ ├── synapse-migrate-room.py
│ ├── synapse-deactivate-user.py
│ ├── synapse-user-admin-rooms.py
│ ├── synapse-user-rooms.py
│ ├── synapse-room-member-flow.py
│ └── synapse-search.py
└── references/
├── synapse-admin-api.md # endpoints used + upstream docs
├── room-health-checks.md # rule definitions
├── room-graph-pipeline.md # periodic SVG dashboard with Docker
└── safety-guide.md # destructive-operation checklist
```
## Safety
These scripts hold an admin token. **Read [`references/safety-guide.md`](references/safety-guide.md) before running anything new.** Highlights:
- `synapse-deactivate-user.py` is irreversible.
- `synapse-migrate-room.py` enables encryption — irreversible — and removes discoverability for users outside the parent space. It prints the plan and asks before the first write; `--yes` skips the question and is required without a terminal.
- `rooms.json` exposes user IDs / power levels for every room. Never commit it.
## License
MIT for code, CC-BY-SA-4.0 for documentation. See [`LICENSE-MIT`](../../LICENSE-MIT) and [`LICENSE-CC-BY-SA-4.0`](../../LICENSE-CC-BY-SA-4.0).
## Credits
Developed and maintained by [Netresearch DTT GmbH](https://www.netresearch.de/). Originally derived from the internal `matrix-tools` Node.js scripts; ported to Python and generalised for any Synapse homeserver.
---
**Made with ❤️ for Open Source by [Netresearch](https://www.netresearch.de/)**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| 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: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |