Skip to content

netresearch/matrix-skill / skills/matrix-communication

matrix-communication

Flagged

Use when communicating via Matrix chat, notifying teams, or managing E2EE. Triggers on #room:server references, Matrix URLs, and chat requests.

FileKindSize
README.mdmarkdown2.9 KB
SKILL.mdskill md6.7 KB
evals/evals.jsonconfig12.6 KB
references/agent-governance.mdmarkdown2.0 KB
references/api-reference.mdmarkdown7.3 KB
references/command-reference.mdmarkdown8.9 KB
references/e2ee-guide.mdmarkdown17.2 KB
references/hookshot-integration.mdmarkdown10.7 KB
references/messaging-guide.mdmarkdown13.8 KB
references/no-editorializing.mdmarkdown331 B
references/setup-guide.mdmarkdown11.1 KB
references/troubleshooting.mdmarkdown7.8 KB
scripts/_lib/__init__.pyscript3.6 KB
scripts/_lib/backup_mac.pyscript1.2 KB
scripts/_lib/config.pyscript4.6 KB
scripts/_lib/daemon_client.pyscript3.0 KB
scripts/_lib/deps.pyscript1.9 KB
scripts/_lib/downloads.pyscript1.1 KB
scripts/_lib/e2ee.pyscript13.2 KB
scripts/_lib/formatting.pyscript14.4 KB
scripts/_lib/http.pyscript4.8 KB
scripts/_lib/reactions.pyscript2.9 KB
scripts/_lib/roomlog.pyscript13.7 KB
scripts/_lib/rooms.pyscript15.5 KB
scripts/_lib/secret_input.pyscript2.0 KB
scripts/_lib/test_backup_mac.pyscript1.5 KB
scripts/_lib/test_config.pyscript7.1 KB
scripts/_lib/test_daemon_client.pyscript5.9 KB
scripts/_lib/test_downloads.pyscript2.3 KB
scripts/_lib/test_e2ee.pyscript14.3 KB
scripts/_lib/test_formatting.pyscript15.5 KB
scripts/_lib/test_http.pyscript4.1 KB
scripts/_lib/test_reactions.pyscript15.2 KB
scripts/_lib/test_roomlog.pyscript20.2 KB
scripts/_lib/test_rooms.pyscript13.7 KB
scripts/_lib/test_secret_input.pyscript2.2 KB
scripts/_lib/test_trust.pyscript8.3 KB
scripts/_lib/trust.pyscript5.3 KB
scripts/_lib/utils.pyscript1.7 KB
scripts/matrix-create-room.pyexecutablescript4.7 KB
scripts/matrix-doctor.pyexecutablescript22.2 KB
scripts/matrix-download-e2ee.pyexecutablescript7.7 KB
scripts/matrix-e2ee-setup.pyexecutablescript9.2 KB
scripts/matrix-e2ee-verify.pyexecutablescript29.2 KB
scripts/matrix-edit-e2ee.pyexecutablescript7.9 KB
scripts/matrix-edit.pyexecutablescript5.3 KB
scripts/matrix-fetch-keys.pyexecutablescript9.1 KB
scripts/matrix-invite.pyexecutablescript3.0 KB
scripts/matrix-key-backup.pyexecutablescript21.3 KB
scripts/matrix-power-level.pyexecutablescript7.0 KB
scripts/matrix-react.pyexecutablescript14.1 KB
scripts/matrix-read-e2ee.pyexecutablescript12.8 KB
scripts/matrix-read.pyexecutablescript4.7 KB
scripts/matrix-redact.pyexecutablescript5.0 KB
scripts/matrix-resolve.pyexecutablescript1.7 KB
scripts/matrix-rooms.pyexecutablescript3.8 KB
scripts/matrix-send-e2ee.pyexecutablescript19.4 KB
scripts/matrix-send.pyexecutablescript9.4 KB
scripts/matrix-watch.pyexecutablescript5.3 KB
scripts/matrix-watchd.pyexecutablescript23.5 KB
scripts/test_matrix_doctor.pyscript14.2 KB
scripts/test_matrix_read_e2ee.pyscript2.7 KB

scripts/matrix-download-e2ee.py

View on GitHub
#!/usr/bin/env -S uv run --script
# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# /// script
# requires-python = ">=3.11"
# dependencies = ["matrix-nio[e2e]<0.26"]
# ///
"""Download media from a Matrix room message.

Usage:
    matrix-download-e2ee.py ROOM EVENT_ID [--output DIR] [--filename NAME]
    matrix-download-e2ee.py --help

Arguments:
    ROOM        Room alias (#room:server), room ID (!id:server), or room name
    EVENT_ID    Event ID of the media message ($xxx:server)

Options:
    --output DIR     Output directory [default: .]
    --filename NAME  Override filename (default: from message body)
    --overwrite      Replace an existing file of that name (default: refuse)
    --debug          Show debug information
    --help           Show this help
"""

import argparse
import asyncio
import os
import sys
from pathlib import Path

sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

from _lib import (
    check_e2ee_dependencies,
    find_room_in_nio_client,
    get_store_path,
    load_config,
    load_credentials,
    normalize_room_input,
    prefer_ipv4,
    restore_login_checked,
    suppress_nio_logging,
)
from _lib.downloads import download_target, write_download

check_e2ee_dependencies()

from nio import (
    AsyncClient,
    AsyncClientConfig,
    DownloadError,
    MemoryDownloadResponse,
    RoomGetEventError,
    RoomResolveAliasResponse,
)


async def download_media(
    config: dict,
    room: str,
    event_id: str,
    output_dir: str = ".",
    filename: str | None = None,
    debug: bool = False,
    overwrite: bool = False,
) -> str:
    """Download media from a Matrix message event."""
    store_path = get_store_path()
    stored_creds = load_credentials()

    if stored_creds and stored_creds.get("user_id") == config["user_id"]:
        device_id = stored_creds["device_id"]
        access_token = stored_creds["access_token"]
    elif "access_token" in config:
        access_token = config["access_token"]
        from nio import WhoamiResponse

        temp_client = AsyncClient(config["homeserver"], config["user_id"])
        temp_client.access_token = access_token
        whoami = await temp_client.whoami()
        await temp_client.close()
        if isinstance(whoami, WhoamiResponse):
            device_id = whoami.device_id
        else:
            raise RuntimeError(f"Failed to get device info: {whoami}")
    else:
        raise RuntimeError("No credentials found. Run matrix-e2ee-setup.py first.")

    client_config = AsyncClientConfig(store_sync_tokens=True, encryption_enabled=True)
    client = AsyncClient(
        homeserver=config["homeserver"],
        user=config["user_id"],
        device_id=device_id,
        store_path=str(store_path),
        config=client_config,
    )

    try:
        restore_login_checked(client, config["user_id"], device_id, access_token)

        if client.store:
            client.load_store()

        if client.should_upload_keys:
            await client.keys_upload()

        # Sync to get room keys
        if debug:
            print("Syncing...", file=sys.stderr)
        await client.sync(timeout=0, full_state=True)

        # Resolve room
        room_id = room
        if room.startswith("#"):
            response = await client.room_resolve_alias(room)
            if isinstance(response, RoomResolveAliasResponse):
                room_id = response.room_id
            else:
                raise RuntimeError(f"Could not resolve room alias: {response}")
        elif not room.startswith("!"):
            found = find_room_in_nio_client(client.rooms, room)
            if found:
                room_id = found
            else:
                raise RuntimeError(
                    f"Could not find room '{room}'. Use 'matrix-rooms.py' to list rooms."
                )

        # Fetch the event
        if debug:
            print(f"Fetching event {event_id}...", file=sys.stderr)

        resp = await client.room_get_event(room_id, event_id)
        if isinstance(resp, RoomGetEventError):
            raise RuntimeError(f"Failed to get event: {resp.message}")  # noqa: TRY004  # preserve RuntimeError contract expected by callers

        event = resp.event
        source = event.source if hasattr(event, "source") else {}
        content = source.get("content", {})
        msgtype = content.get("msgtype", "")

        if msgtype not in ("m.image", "m.file", "m.video", "m.audio"):
            raise RuntimeError(f"Event is not a media message (msgtype: {msgtype})")

        # Get mxc URL
        if "file" in content:
            mxc_url = content["file"]["url"]
        elif "url" in content:
            mxc_url = content["url"]
        else:
            raise RuntimeError("No media URL found in event")

        if debug:
            print(f"Downloading {mxc_url}...", file=sys.stderr)

        # The name comes from the message unless --filename is given; only its
        # last component is used. An existing file is kept unless --overwrite.
        out_path = download_target(output_dir, filename or content.get("body"))
        if out_path.exists() and not overwrite:
            raise RuntimeError(
                f"{out_path} exists; pass --overwrite to replace it or "
                "--filename to choose another name"
            )

        # Download media into memory (don't pass filename to avoid unnecessary disk write)
        resp = await client.download(mxc=mxc_url)

        if isinstance(resp, DownloadError):
            raise RuntimeError(f"Download failed: {resp.message}")  # noqa: TRY004  # preserve RuntimeError contract expected by callers

        # Get raw bytes
        if isinstance(resp, MemoryDownloadResponse):
            data = resp.body
        else:
            data = Path(resp.filename).read_bytes()

        # Decrypt E2EE media if encrypted
        if "file" in content:
            from nio.crypto import decrypt_attachment

            file_info = content["file"]
            data = decrypt_attachment(
                ciphertext=data,
                key=file_info["key"]["k"],
                hash=file_info["hashes"]["sha256"],
                iv=file_info["iv"],
            )

        # Save to file
        out_path.parent.mkdir(parents=True, exist_ok=True)
        write_download(out_path, data, overwrite=overwrite)

        if debug:
            print(
                f"Saved to {out_path} ({out_path.stat().st_size:,} bytes)",
                file=sys.stderr,
            )

        return str(out_path)

    finally:
        await client.close()


def main():
    parser = argparse.ArgumentParser(description="Download media from Matrix room")
    parser.add_argument("room", help="Room alias, ID, or name")
    parser.add_argument("event_id", help="Event ID of the media message")
    parser.add_argument("--output", default=".", help="Output directory [default: .]")
    parser.add_argument("--filename", help="Override filename")
    parser.add_argument(
        "--overwrite",
        action="store_true",
        help="Replace an existing file of the same name (default: refuse)",
    )
    parser.add_argument("--debug", action="store_true", help="Debug output")
    args = parser.parse_args()

    suppress_nio_logging()
    prefer_ipv4()

    config = load_config()

    try:
        path = asyncio.run(
            download_media(
                config,
                normalize_room_input(args.room),
                args.event_id,
                output_dir=args.output,
                filename=args.filename,
                debug=args.debug,
                overwrite=args.overwrite,
            )
        )
        print(path)
    except Exception as e:
        if args.debug:
            raise
        print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


if __name__ == "__main__":
    main()
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
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: 194kUpdated Claude CodeCodexVerifiedInstall