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-read-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"]
# ///
"""Read recent messages from an E2EE Matrix room.

Requires libolm system library:
    Debian/Ubuntu: sudo apt install libolm-dev
    Fedora:        sudo dnf install libolm-devel
    macOS 26+:     unsupported, python-olm build fails (Clang 17); see setup-guide.md

Usage:
    matrix-read-e2ee.py ROOM [--limit N] [--json] [--request-keys]
    matrix-read-e2ee.py --help

Arguments:
    ROOM        Room alias (#room:server), room ID (!id:server), or room name

Options:
    --limit N            Number of messages to retrieve [default: 10]
    --request-keys       Request keys from other devices for undecryptable messages
    --json               Output as JSON
    --debug              Show debug information
    --help               Show this help

Note: First run takes ~2-5s for initial sync and key setup.
      With --request-keys, wait for other devices to respond (may take 10-30s).
"""

import asyncio
import json
import os
import sys

# Add script directory to path for _lib imports
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))

from _lib import (
    check_e2ee_dependencies,
    clean_message,
    find_room_in_nio_client,
    format_timestamp,
    get_store_path,
    load_config,
    load_credentials,
    normalize_room_input,
    prefer_ipv4,
    restore_login_checked,
    rich_text_fields,
    suppress_nio_logging,
)

# Check dependencies before importing nio
check_e2ee_dependencies()

from nio import (
    AsyncClient,
    AsyncClientConfig,
    MegolmEvent,
    RoomMessageEmote,
    RoomMessagesResponse,
    RoomMessageText,
    RoomResolveAliasResponse,
)

sys.stdout.reconfigure(line_buffering=True)
sys.stderr.reconfigure(line_buffering=True)


def process_event(event, debug=False) -> tuple[dict | None, bool]:
    """Process a timeline event into a message dict.

    Returns (message_dict, is_undecryptable)
    """
    if debug:
        print(f"  Event type: {type(event).__name__}", file=sys.stderr)

    if isinstance(event, RoomMessageText):
        return {
            "sender": event.sender,
            "body": event.body,
            "msgtype": "m.text",
            "timestamp": event.server_timestamp,
            "event_id": event.event_id,
            "encrypted": False,
            **rich_text_fields(event.source.get("content")),
        }, False
    elif isinstance(event, RoomMessageEmote):
        return {
            "sender": event.sender,
            "body": event.body,
            "msgtype": "m.emote",
            "timestamp": event.server_timestamp,
            "event_id": event.event_id,
            "encrypted": False,
            **rich_text_fields(event.source.get("content")),
        }, False
    elif isinstance(event, MegolmEvent):
        return {
            "sender": event.sender,
            "body": "[Unable to decrypt]",
            "msgtype": "m.room.encrypted",
            "timestamp": event.server_timestamp,
            "event_id": event.event_id,
            "encrypted": True,
            "session_id": event.session_id if hasattr(event, "session_id") else None,
        }, True
    elif hasattr(event, "source") and event.source.get("type") == "m.room.message":
        content = event.source.get("content", {})
        msg = {
            "sender": event.sender,
            "body": content.get("body", ""),
            "msgtype": content.get("msgtype", "m.text"),
            "timestamp": event.server_timestamp,
            "event_id": event.event_id,
            "encrypted": True,
            **rich_text_fields(content),
        }
        # Include media fields when present (m.image, m.file, m.video, m.audio)
        # Only expose mxc URL, not E2EE decryption keys (use download script for that)
        if "file" in content:
            msg["url"] = content["file"].get("url", "")
        elif "url" in content:
            msg["url"] = content["url"]
        if "info" in content:
            msg["info"] = {
                k: v
                for k, v in content["info"].items()
                if k in ("mimetype", "size", "w", "h")
            }
        return msg, False

    return None, False


async def read_messages_e2ee(
    config: dict,
    room: str,
    limit: int = 10,
    request_keys: bool = False,
    debug: bool = False,
) -> list:
    """Read messages from an E2EE room."""

    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"]
        if debug:
            print(f"Using dedicated device: {device_id}", file=sys.stderr)
    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
            if debug:
                print(f"Using existing device: {device_id}", file=sys.stderr)
        else:
            return [{"error": f"Failed to get device info: {whoami}"}]
    else:
        return [{"error": "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,
    )

    messages = []
    undecryptable_events = []

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

        if client.store:
            client.load_store()

        if client.should_upload_keys:
            if debug:
                print("Uploading device keys...", file=sys.stderr)
            await client.keys_upload()

        # Sync first (timeout=0 = no long-poll), then resolve room from client.rooms
        if debug:
            print("Syncing...", file=sys.stderr)

        await client.sync(timeout=0, full_state=True)

        # Resolve room: alias via server, name via client.rooms (post-sync)
        room_id = room
        if room.startswith("#"):
            response = await client.room_resolve_alias(room)
            if isinstance(response, RoomResolveAliasResponse):
                room_id = response.room_id
                if debug:
                    print(f"Resolved alias {room} -> {room_id}", file=sys.stderr)
            else:
                return [{"error": 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
                if debug:
                    print(f"Found room by name: {room} -> {room_id}", file=sys.stderr)
            else:
                return [
                    {
                        "error": f"Could not find room '{room}'. Use 'matrix-rooms.py' to list rooms."
                    }
                ]

        if debug:
            print(f"Sync complete. Rooms: {len(client.rooms)}", file=sys.stderr)

        room_obj = client.rooms.get(room_id)
        if not room_obj:
            return [{"error": f"Room not found: {room_id}"}]

        if debug:
            print(f"Room encrypted: {room_obj.encrypted}", file=sys.stderr)

        if client.should_query_keys:
            if debug:
                print("Querying device keys...", file=sys.stderr)
            await client.keys_query()

        if debug:
            print("Fetching messages...", file=sys.stderr)

        msg_response = await client.room_messages(
            room_id=room_id, start="", limit=limit
        )

        if isinstance(msg_response, RoomMessagesResponse):
            for event in msg_response.chunk:
                msg, is_undecryptable = process_event(event, debug)
                if msg:
                    messages.append(msg)
                    if is_undecryptable:
                        undecryptable_events.append(event)

        # Request keys for undecryptable messages
        if request_keys and undecryptable_events:
            if debug:
                print(
                    f"\nRequesting keys for {len(undecryptable_events)} undecryptable messages...",
                    file=sys.stderr,
                )

            keys_requested = set()
            for event in undecryptable_events:
                if (
                    hasattr(event, "session_id")
                    and event.session_id not in keys_requested
                ):
                    keys_requested.add(event.session_id)
                    try:
                        await client.request_room_key(event)
                        if debug:
                            print(
                                f"  Requested key for session {event.session_id[:16]}...",
                                file=sys.stderr,
                            )
                    except Exception as e:  # noqa: BLE001  # intentional fail-soft: error surfaced to caller, not re-raised
                        if debug:
                            print(f"  Failed to request key: {e}", file=sys.stderr)

            if keys_requested:
                if debug:
                    print(
                        f"\nWaiting for {len(keys_requested)} key(s) to arrive...",
                        file=sys.stderr,
                    )

                for i in range(6):
                    await asyncio.sleep(5)
                    await client.sync(timeout=5000)
                    if debug:
                        print(f"  Sync {i + 1}/6...", file=sys.stderr)

                if debug:
                    print("\nRetrying decryption...", file=sys.stderr)

                messages = []
                msg_response = await client.room_messages(
                    room_id=room_id, start="", limit=limit
                )

                if isinstance(msg_response, RoomMessagesResponse):
                    decrypted_count = 0
                    still_encrypted = 0
                    for event in msg_response.chunk:
                        msg, is_undecryptable = process_event(event, debug)
                        if msg:
                            messages.append(msg)
                            if is_undecryptable:
                                still_encrypted += 1
                            elif msg.get("encrypted"):
                                decrypted_count += 1

                    if debug:
                        print(
                            f"  Decrypted: {decrypted_count}, Still encrypted: {still_encrypted}",
                            file=sys.stderr,
                        )

        return messages

    finally:
        await client.close()


def main():
    import argparse

    parser = argparse.ArgumentParser(
        description="Read messages from an E2EE Matrix room"
    )
    parser.add_argument(
        "room", help="Room alias (#room:server), room ID (!id:server), or room name"
    )
    parser.add_argument(
        "--limit", "-l", type=int, default=10, help="Number of messages (default: 10)"
    )
    parser.add_argument(
        "--request-keys",
        "-k",
        action="store_true",
        help="Request keys from other devices for undecryptable messages",
    )
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--debug", action="store_true", help="Show debug info")

    args = parser.parse_args()

    prefer_ipv4()
    if not args.debug:
        suppress_nio_logging()

    config = load_config(require_user_id=True)

    # Room name resolution happens post-sync inside the async function
    room_input = normalize_room_input(clean_message(args.room))
    room = room_input

    messages = asyncio.run(
        read_messages_e2ee(
            config=config,
            room=room,
            limit=args.limit,
            request_keys=args.request_keys,
            debug=args.debug,
        )
    )

    if messages and "error" in messages[0]:
        print(f"Error: {messages[0]['error']}", file=sys.stderr)
        sys.exit(1)

    if args.json:
        print(json.dumps(messages, indent=2))
    else:
        if not messages:
            print("No messages found")
            return

        for msg in messages:
            ts = format_timestamp(msg.get("timestamp", 0))
            sender = msg["sender"].split(":")[0].lstrip("@")
            body = msg["body"]
            if len(body) > 100:
                body = body[:100] + "..."
            encrypted_marker = " [E2EE]" if msg.get("encrypted") else ""
            print(f"[{ts}] {sender}{encrypted_marker}: {body}")


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