netresearch/matrix-skill / skills/matrix-communication
matrix-communication
FlaggedUse when communicating via Matrix chat, notifying teams, or managing E2EE. Triggers on #room:server references, Matrix URLs, and chat requests.
references/command-reference.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Command Reference
Every script in this skill, with the flags that are not obvious from `--help`.
`SKILL.md` carries only the handful used in almost every session; this is the
full surface.
`ROOM` is a short name (`test`), a room ID (`!abc:server`), an alias
(`#room:server`) or a `https://matrix.to/#/…` link copied from Element
everywhere below. A room without a name — a direct chat, usually — goes by
the name Element shows for it: the other person's display name, or their
user ID (`@jane:server`). Resolving such names costs one request per unnamed
room on the paths that do not sync.
**Prepend `set +H &&` whenever an argument contains `!`** — bash history
expansion mangles it otherwise, and the corruption is silent.
## Send
```bash
set +H && uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "message"
set +H && uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "text" --mention '@user:server'
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "message" --no-prefix # bot commands (!hookshot …) need it when bot_prefix is set; see hookshot-integration.md for encrypted rooms
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "is deploying" --emote
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "📦 Release: …" --notice
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "reply" --thread '$rootEventId'
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py ROOM "reply" --reply '$eventId'
set +H && uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-send-e2ee.py --to '@user:server' "message"
```
- `--to @user:server` replaces `ROOM` and sends to the existing direct chat
with that person. Where `ROOM` finds a direct chat by the name it is shown
under, `--to` reads the account data `m.direct`, which marks it as direct
even when it has a name or the person is in other rooms with you. That list
keeps rooms after a leave, so a room counts only when you are joined and
the other person is joined or invited. No usable room, or more than one, is
an error that names the rooms — `--to` never creates a room, and with
several it does not guess: pass the room ID.
- `--mention` is what notifies. A plain `@name` in the text notifies nobody —
only `m.mentions` does. `--mention-room` for `@room`.
- `--notice` sends `m.notice`, which other bots do not auto-reply to. Use it for
unattended automation; mutually exclusive with `--emote`.
- In an encrypted room the message key goes to verified devices only. If the
room has unverified devices, the send is refused and lists them. Verify them,
or pass `--trust-unverified-devices` to share this one message's key with
them anyway; the flag is not remembered and marks no device verified. The
same flag exists on `matrix-edit-e2ee.py` and `matrix-react.py` (and is
passed to the daemon when it sends).
## Read, download, edit, delete, react
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-read-e2ee.py ROOM --limit 10
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-read-e2ee.py ROOM --limit 20 --json
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-download-e2ee.py ROOM '$eventId' --output ./downloads # --overwrite to replace an existing file
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-edit-e2ee.py ROOM '$eventId' "new text"
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-redact.py ROOM '$eventId' --reason "reason"
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-react.py ROOM '$eventId' "✅"
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-react.py ROOM '$eventId' "▶️" "🤖" # several in one call, in order
# status swap: set ✅, remove this account's own ▶️/🩹 on that event (looked up, no id needed)
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-react.py ROOM '$eventId' "✅" --replace "▶️" "🩹"
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-react.py ROOM '$eventId' "▶️" --remove
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-react.py ROOM '$eventId' --list # own reactions, changes nothing
```
`--json` output carries `format` and `formatted_body` next to `body` when the
event has them. `body` is only the plain-text fallback and can differ from what
Element shows: a hookshot webhook message without a `text` key has
`Received webhook data:` plus the raw JSON in `body` and the rendered HTML in
`formatted_body` (see `hookshot-integration.md`). Judge how a message renders
from `formatted_body`, never from `body` alone.
`--json` output includes the media URL and info for `m.image` / `m.file` /
`m.video` / `m.audio` events; `matrix-download-e2ee.py` decrypts and saves by
event ID. It keeps an existing file of the same name (pass `--overwrite` or
`--filename`) and writes new files readable by your account only.
## Live awareness
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-watchd.py --start | --status | --stop
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-watch.py ROOM [--cursor NAME] [--once]
```
The daemon owns the store for its whole run; everything else routes through it.
## Rooms and membership
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-rooms.py
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-rooms.py --search ops
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-rooms.py --lookup "Jane Doe" # direct chat by name
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-resolve.py "#room:server"
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-create-room.py "Room Name" --alias localpart --invite '@user:server'
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-invite.py ROOM '@user:server'
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-power-level.py ROOM --show
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-power-level.py ROOM --set '@user:server' 50
```
Run `--show` before `--set` on any room you did not create — see
`api-reference.md` for what the levels mean.
## E2EE
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-e2ee-setup.py --status
MATRIX_PASSWORD="pass" uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-e2ee-setup.py
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-e2ee-verify.py --request DEVICE --timeout 180
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-e2ee-verify.py --listen --timeout 180 # own devices; --accept-from USER for another
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-e2ee-verify.py --list
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-fetch-keys.py ROOM --sync-time 60
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-key-backup.py --recovery-key --import-keys # prompts; or MATRIX_RECOVERY_KEY
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-key-backup.py --import-keys
```
- Pass the password through `MATRIX_PASSWORD`, never as an argument — special
characters do not survive the shell.
- `--listen` lets Element initiate; prefer it over `--request` when several
sessions exist. Use Element Desktop or Android — Element X has an incompatible
verification flow.
- `--import-keys` is what stores restored keys. Without it they are displayed and
lost.
## Health check
```bash
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-doctor.py --install
uv run ${CLAUDE_SKILL_DIR}/scripts/matrix-doctor.py --offline
```
`matrix-doctor.py` runs under `uv run` like the other scripts but declares no
dependency, so it starts on hosts where nio's olm binding cannot be built.
Its `matrix_nio` row asks uv to build the environment the E2EE scripts get
(`matrix-nio[e2e]<0.26` on Python 3.11 or later) and shows uv's error when
that fails. `--offline` skips the homeserver call, and the token row then
reads `not verified` rather than OK; the `matrix_nio` probe then runs
`uv run --offline` and uses only what uv has cached.
## Script selection
| Operation | E2EE (preferred) | Non-E2EE fallback |
|-----------|-----------------|-------------------|
| Send | `matrix-send-e2ee.py` | `matrix-send.py` |
| Read | `matrix-read-e2ee.py` | `matrix-read.py` |
| Edit | `matrix-edit-e2ee.py` | `matrix-edit.py` |
| Download | `matrix-download-e2ee.py` | — |
| React | `matrix-react.py` | (same) |
| Delete | `matrix-redact.py` | (same) |
Fall back to the non-E2EE scripts only for a room confirmed to be unencrypted. The one exception is a bot command to a bridge that does not decrypt (see [hookshot-integration.md](hookshot-integration.md)), and only for content you are fine to disclose to the homeserver.
## Config
`~/.config/matrix/config.json`
| Key | |
|---|---|
| `homeserver` | required |
| `user_id` | required |
| `access_token` | optional, **non-E2EE scripts only** |
| `access_token_file` | optional: path to a file holding `access_token` (relative to the config directory), so the token stays out of `config.json` |
| `watch_rooms` | rooms `matrix-watchd.py` logs |
| `bot_prefix` | message prefix |
`MATRIX_ACCESS_TOKEN` in the environment overrides `access_token_file`, which
overrides `access_token` (`_lib/config.py`, `resolve_tokens`). Rotating the
token means replacing that one value; the rest of `config.json` stays as it is.
Copy `access_token` from the skill's own `credentials.json` (setup-guide, step
6) — never from a client you use. The reason is in `SKILL.md`, and it is the one
mistake in this skill that damages something outside it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |