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-send-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"]
# ///
"""Send an E2EE-capable message to a 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-send-e2ee.py ROOM MESSAGE [OPTIONS]
    matrix-send-e2ee.py --to @user:server MESSAGE [OPTIONS]
    matrix-send-e2ee.py --help

Arguments:
    ROOM        Room identifier. Supports multiple formats:
                - Room ID: !abc123xyz (direct, fastest)
                - Room alias: #room:server (resolved via directory)
                - Room name: "agent-work" (looked up from joined rooms)
    MESSAGE     Message content (markdown supported)

Options:
    --emote           Send as /me action (m.emote)
    --notice          Send as m.notice — bot-flagged, suppressed from auto-reply
                      loops. Use for unattended automation (release announcements,
                      CI summaries, scheduled digests). Mutually exclusive with --emote.
    --thread EVENT    Reply in thread (event ID of thread root)
    --reply EVENT     Reply to message (event ID to reply to)
    --to USER         Send to the existing direct chat with USER (@user:server)
                      instead of ROOM; never creates a room
    --no-prefix       Don't add bot_prefix from config
    --json            Output as JSON
    --quiet           Minimal output
    --debug           Show debug information
    --help            Show this help

Note: First run takes ~2-5s for initial sync and key setup.
      Subsequent runs use cached keys (~2-3s).

Examples:
    # Send by room name (easiest)
    matrix-send-e2ee.py agent-work "Hello team!"

    # Send by room ID
    matrix-send-e2ee.py '!sZBoTOreI1z0BgHY-s2ZC9MV63B1orGFigPXvYMQ22E' "Hello!"

    # Send by alias
    matrix-send-e2ee.py '#general:matrix.org' "Hello everyone!"

    # Send to the direct chat with a person
    matrix-send-e2ee.py --to '@jane:matrix.org' "Hello Jane!"
"""

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 (
    UntrustedDevicesError,
    add_bot_prefix,
    build_mentions,
    check_e2ee_dependencies,
    clean_message,
    daemon_request,
    find_direct_room,
    find_room_in_nio_client,
    get_store_path,
    inject_pills,
    load_config,
    load_credentials,
    markdown_to_html,
    normalize_room_input,
    prefer_ipv4,
    restore_login_checked,
    send_checked,
    suppress_nio_logging,
)

# Check dependencies before importing nio
check_e2ee_dependencies()

from nio import (
    AsyncClient,
    AsyncClientConfig,
    RoomResolveAliasResponse,
    RoomSendResponse,
)

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


async def send_message_e2ee(
    config: dict,
    room: str,
    message: str,
    emote: bool = False,
    notice: bool = False,
    thread_id: str | None = None,
    reply_id: str | None = None,
    mentions: list | None = None,
    mention_room: bool = False,
    debug: bool = False,
    trust_unverified_devices: bool = False,
) -> dict:
    """Send an E2EE-capable message to a Matrix room.

    msgtype precedence: notice > emote > text. The caller is expected to pass
    only one of `notice` or `emote`; the CLI enforces this via a mutually
    exclusive argument group.
    """

    # A running daemon holds the store, so a direct open here would be the
    # second one - the state that corrupts it. Delegate instead. The signal is
    # a socket that answers, never the store lock: a direct send holds that
    # lock too, so routing on it would aim at a socket nobody serves. None
    # means nothing is listening; an error response is an answer and is
    # returned, because falling through on it would send the message twice.
    msgtype = "m.notice" if notice else ("m.emote" if emote else "m.text")
    response = daemon_request(
        {
            "op": "send",
            "room": room,
            "body": message,
            "msgtype": msgtype,
            "reply_to": reply_id,
            "thread_root": thread_id,
            "mentions": mentions,
            "mention_room": mention_room,
            "trust_unverified_devices": trust_unverified_devices,
        }
    )
    if response is not None:
        if response.get("ok"):
            return {"event_id": response["event_id"], "room_id": room}
        return {"error": response.get("error", "daemon refused the message")}

    store_path = get_store_path()

    # Check for E2EE device credentials
    # Priority: 1) Dedicated device from setup, 2) Access token from config
    stored_creds = load_credentials()

    if stored_creds and stored_creds.get("user_id") == config["user_id"]:
        # Use dedicated E2EE device (created via matrix-e2ee-setup.py)
        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:
        # Use access token from config (reuses existing device)
        access_token = config["access_token"]
        # Get device_id from server
        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 from token: {device_id}", file=sys.stderr)
        else:
            return {"error": f"Failed to get device info: {whoami}"}
    else:
        return {
            "error": "No credentials found. Add 'access_token' to config, or run matrix-e2ee-setup.py"
        }

    if debug:
        print(f"Store path: {store_path}", file=sys.stderr)

    # Configure client for E2EE
    client_config = AsyncClientConfig(
        store_sync_tokens=True,
        encryption_enabled=True,
    )

    # Create client
    client = AsyncClient(
        homeserver=config["homeserver"],
        user=config["user_id"],
        device_id=device_id,
        store_path=str(store_path),
        config=client_config,
    )

    try:
        # Restore session from stored credentials
        restore_login_checked(client, config["user_id"], device_id, access_token)
        if debug:
            print("Session restored", file=sys.stderr)

        if debug:
            print(f"Store initialized: {client.store is not None}", file=sys.stderr)
            print(f"Olm initialized: {client.olm is not None}", file=sys.stderr)

        # Load existing crypto keys from store
        if client.store:
            client.load_store()
            if debug:
                print(
                    f"Keys loaded. Olm account shared: {client.olm_account_shared}",
                    file=sys.stderr,
                )

        # Upload device keys if needed
        if client.should_upload_keys:
            if debug:
                print("Uploading device keys...", file=sys.stderr)
            from nio import KeysUploadResponse

            keys_response = await client.keys_upload()
            if isinstance(keys_response, KeysUploadResponse):
                if debug:
                    print("Keys uploaded successfully", file=sys.stderr)
            else:
                if debug:
                    print(f"Keys upload response: {keys_response}", file=sys.stderr)

        # Sync first to populate client.rooms (timeout=0 = no long-poll).
        if debug:
            print("Syncing (timeout=0, full_state=True)...", file=sys.stderr)

        sync_response = await client.sync(timeout=0, full_state=True)
        if (
            hasattr(sync_response, "transport_response")
            and sync_response.transport_response.status != 200
        ):
            return {"error": f"Sync failed: {sync_response}"}

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

        # 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("!"):
            # Plain name — resolve from synced rooms (no HTTP calls)
            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 available rooms."
                }

        # Get room object and check encryption
        room_obj = client.rooms.get(room_id)
        if debug:
            print(f"Room object: {room_obj is not None}", file=sys.stderr)
            if room_obj:
                print(f"Room encrypted: {room_obj.encrypted}", file=sys.stderr)
            print(f"Olm loaded: {client.olm is not None}", file=sys.stderr)

        if room_obj and room_obj.encrypted and client.olm:
            # Always include own user so own devices get Olm sessions established.
            # should_query_keys is False when own keys were last queried recently, which
            # causes share_group_session to skip own devices and fail to deliver Megolm keys.
            if hasattr(client, "users_for_key_query"):
                client.users_for_key_query.add(config["user_id"])

            # Query device keys for all room members
            if client.should_query_keys:
                if debug:
                    print("Querying device keys...", file=sys.stderr)
                from nio import KeysQueryResponse

                keys_query_response = await client.keys_query()
                if debug:
                    if isinstance(keys_query_response, KeysQueryResponse):
                        print("Keys query successful", file=sys.stderr)
                    else:
                        print(
                            f"Keys query response: {keys_query_response}",
                            file=sys.stderr,
                        )

            # Claim one-time keys for devices we don't have sessions with
            try:
                users_to_claim = client.get_users_for_key_claiming()
                if users_to_claim:
                    if debug:
                        print(
                            f"Claiming keys for {len(users_to_claim)} users...",
                            file=sys.stderr,
                        )
                    from nio import KeysClaimResponse

                    claim_response = await client.keys_claim(users_to_claim)
                    if debug:
                        if isinstance(claim_response, KeysClaimResponse):
                            print("Keys claimed successfully", file=sys.stderr)
                        else:
                            print(
                                f"Keys claim response: {claim_response}",
                                file=sys.stderr,
                            )
            except Exception as e:  # noqa: BLE001  # intentional fail-soft: error surfaced to caller, not re-raised
                if debug:
                    print(f"Key claiming skipped: {e}", file=sys.stderr)

        # Build message content with HTML formatting
        if notice:
            msgtype = "m.notice"
        elif emote:
            msgtype = "m.emote"
        else:
            msgtype = "m.text"
        content = {
            "msgtype": msgtype,
            "body": message,
        }

        # m.mentions is what actually notifies (MSC3952). A plain @name in the
        # body only ever matched the legacy push rule, and only on an exact
        # localpart - "@bjoern" never reached "bjoern.marten".
        mention_block = build_mentions(mentions, room=mention_room)
        if mention_block:
            content["m.mentions"] = mention_block

        # Pills go into the HTML body only. The plain body keeps the bare name,
        # which is what a client without HTML shows and what the legacy rule
        # reads.
        html = markdown_to_html(inject_pills(message, mentions))
        if html != message:
            content["format"] = "org.matrix.custom.html"
            content["formatted_body"] = html

        # Thread reply
        if thread_id:
            content["m.relates_to"] = {
                "rel_type": "m.thread",
                "event_id": thread_id,
                "is_falling_back": True,
                "m.in_reply_to": {"event_id": reply_id or thread_id},
            }
        elif reply_id:
            content["m.relates_to"] = {"m.in_reply_to": {"event_id": reply_id}}

        # The room key goes to verified devices only, unless the caller opted
        # in for this send (see _lib/trust.py).
        members = list(room_obj.users) if room_obj and room_obj.encrypted else []
        try:
            response = await send_checked(
                client,
                room_id,
                members,
                "m.room.message",
                content,
                trust_unverified=trust_unverified_devices,
            )
        except UntrustedDevicesError as exc:
            return {"error": str(exc)}

        if isinstance(response, RoomSendResponse):
            return {"event_id": response.event_id, "room_id": room_id}
        else:
            return {"error": str(response)}

    finally:
        await client.close()


def resolve_direct_target(config: dict, user_id: str, json_out: bool) -> str:
    """Return the room ID of the direct chat with `user_id`, or exit 1."""
    stored_creds = load_credentials()
    if stored_creds and stored_creds.get("user_id") == config["user_id"]:
        token = stored_creds["access_token"]
    else:
        token = config.get("access_token")
    try:
        if not token:
            raise ValueError(
                "No credentials found. Add 'access_token' to config, "
                "or run matrix-e2ee-setup.py"
            )
        return find_direct_room({**config, "access_token": token}, user_id)
    except ValueError as e:
        if json_out:
            print(json.dumps({"error": str(e)}))
        else:
            print(f"Error: {e}", file=sys.stderr)
        sys.exit(1)


def main():
    import argparse

    parser = argparse.ArgumentParser(
        description="Send an E2EE-capable message to a Matrix room"
    )
    parser.add_argument(
        "room",
        nargs="?",
        help="Room ID (!id), alias (#room:server), or name. Omit with --to",
    )
    parser.add_argument("message", help="Message content")
    parser.add_argument(
        "--to",
        metavar="@user:server",
        help="Send to the existing direct chat with this user instead of ROOM. "
        "Found through m.direct; never creates a room",
    )
    msgtype_group = parser.add_mutually_exclusive_group()
    msgtype_group.add_argument(
        "--emote", action="store_true", help="Send as /me action (m.emote msgtype)"
    )
    msgtype_group.add_argument(
        "--notice",
        action="store_true",
        help="Send as m.notice — bot-flagged, suppressed from auto-reply loops. "
        "Use for unattended automation (release announcements, CI summaries).",
    )
    parser.add_argument(
        "--thread", metavar="EVENT_ID", help="Reply in thread (event ID of thread root)"
    )
    parser.add_argument(
        "--reply", metavar="EVENT_ID", help="Reply to message (event ID)"
    )
    parser.add_argument(
        "--no-prefix", action="store_true", help="Don't add bot_prefix from config"
    )
    parser.add_argument(
        "--mention",
        action="append",
        metavar="@user:server",
        help="Notify this user (repeatable). Sets m.mentions and pills the name "
        "where it appears in the text",
    )
    parser.add_argument(
        "--mention-room",
        action="store_true",
        help="Notify everyone in the room (@room)",
    )
    parser.add_argument(
        "--trust-unverified-devices",
        action="store_true",
        help="Share this message's room key with devices that are not verified. "
        "By default the message is not sent while the room has such devices.",
    )
    parser.add_argument("--json", action="store_true", help="Output as JSON")
    parser.add_argument("--quiet", "-q", action="store_true", help="Minimal output")
    parser.add_argument("--debug", action="store_true", help="Show debug info")

    # Intermixed, so ROOM and MESSAGE are told apart around --to wherever
    # it stands; plain parse_args would fill MESSAGE first.
    args = parser.parse_intermixed_args()

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

    if (args.room is None) == (args.to is None):
        parser.error("give exactly one of ROOM or --to @user:server")

    config = load_config(require_user_id=True)

    # Clean message from bash escaping artifacts
    message = clean_message(args.message)
    if args.to:
        room_input = resolve_direct_target(config, args.to, args.json)
        args.room = args.to  # the confirmation names the person, not the ID
    else:
        room_input = normalize_room_input(clean_message(args.room))

    # Room resolution: IDs and aliases are passed through directly.
    # Plain names are resolved AFTER sync (in the async function) using
    # client.rooms, which avoids 193 HTTP calls from find_room_by_name().
    room = room_input
    if room_input.startswith("!"):
        if args.debug:
            print(f"Using room ID directly: {room_input}", file=sys.stderr)
    elif room_input.startswith("#") and ":" not in room_input:
        # Bare alias without server part — treat as name for post-sync lookup
        room = room_input.lstrip("#")
        if args.debug:
            print(
                f"Treating '{room_input}' as room name for post-sync lookup",
                file=sys.stderr,
            )

    # Add bot prefix if configured (unless --no-prefix or emote)
    if not args.no_prefix and not args.emote and config.get("bot_prefix"):
        message = add_bot_prefix(message, config["bot_prefix"])

    # Run async send
    result = asyncio.run(
        send_message_e2ee(
            config=config,
            room=room,
            message=message,
            emote=args.emote,
            notice=args.notice,
            thread_id=args.thread,
            reply_id=args.reply,
            mentions=args.mention,
            mention_room=args.mention_room,
            debug=args.debug,
            trust_unverified_devices=args.trust_unverified_devices,
        )
    )

    if "error" in result:
        if args.json:
            print(json.dumps(result))
        else:
            print(f"Error: {result['error']}", file=sys.stderr)
        sys.exit(1)

    if args.json:
        print(json.dumps(result))
    elif args.quiet:
        print(result.get("event_id", ""))
    else:
        print(f"Message sent to {args.room}")
        print(f"Event ID: {result.get('event_id')}")


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