New advertisers: 50% off your first month with code FIRSTMONTHSee slots

Matrix chat from an agent: installs Element and matrix-commander, then sends, reads, and lists rooms.

version
1.1.0
GitHub stars
32
View on GitHub

What it does

  • Adds 6 skills: install-client, cli-login, check-login, list-rooms, send-message, and read-messages
  • Covers setup end to end: installing Element Desktop and the matrix-commander CLI, then logging in by password or SSO
  • Stores credentials and the encryption store in ~/.config/matrix-commander/, passing those paths explicitly on every call
  • Designed for agents that need to check login state, post notices or files, and read recent messages in a room

Matrix chat from an agent: install Element and the matrix-commander CLI, log in (password or SSO), list rooms, send and read messages, check which accounts and devices are signed in.

Add marketplace

/plugin marketplace add danielrosehill/Claude-Code-Plugins

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install matrix-client@danielrosehill

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Check Matrix login status

Reports, for each client, whether a session exists, the user id, homeserver and device id. Read-only: changes nothing.

Steps

  1. Element Desktop session. Element keeps the session in Chromium localStorage (LevelDB). Read the keys mx_user_id, mx_hs_url, mx_device_id from it:
    for d in "${XDG_CONFIG_HOME:-$HOME/.config}/Element" "$HOME/.var/app/im.riot.Riot/config/Element" "$HOME/Library/Application Support/Element"; do
      [ -d "$d/Local Storage/leveldb" ] || continue
      echo "== $d"
      strings "$d/Local Storage/leveldb/"* 2>/dev/null | grep -A1 -E '^(mx_user_id|mx_hs_url|mx_device_id)$' | grep -v -- '^--$'
    done
    
    The value is the line after each key; it can carry a one-byte prefix (e.g. !), strip it. LevelDB keeps old values until compaction: if several user ids show up, the last pair printed is usually the current one. Confirm visually in Element (avatar menu) if it matters. No output = Element never logged in on this profile (or a different Element profile is used).
  2. CLI session.
    MC_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/matrix-commander"
    mc() { matrix-commander -c "$MC_DIR/credentials.json" -s "$MC_DIR/store" "$@"; }
    if [ -f "$MC_DIR/credentials.json" ]; then
      jq '{homeserver, user_id, device_id, room_id}' "$MC_DIR/credentials.json"
      mc --whoami 2>&1 | tail -n 3
    else
      echo "CLI not logged in: no $MC_DIR/credentials.json"
    fi
    
    --whoami returning the user id proves the access token is still valid on the server; the file existing alone does not. Never print access_token.
  3. Cross-check devices (only if the CLI is logged in): mc --devices 2>&1 | tail -n 30 lists every device of the account; the Element mx_device_id should appear there.
  4. Report a short table: client, logged in (yes/no), user id, homeserver, device id, verified by (--whoami / localStorage only). If the CLI is not logged in, offer cli-login.

Notes

  • Element's localStorage check is a local read; it does not prove the token is still valid. Only the CLI --whoami hits the server.

Readme

Matrix Client

Set up Matrix on a computer and use it from an AI agent: install Element Desktop and the matrix-commander CLI, log in, check which accounts and devices are signed in.

Skills

  • install-client — install Element Desktop (apt, Flatpak, Homebrew, winget) and matrix-commander (uv tool / pipx)
  • check-login — is Element logged in, is the CLI logged in, as which user, on which homeserver and device
  • cli-login — log matrix-commander in (password or SSO) as a new device, then emoji-verify it against Element
  • list-rooms — rooms the account is in: names, ids, aliases, encryption, members
  • send-message — send text, Markdown, a notice or a file to a room
  • read-messages — last N messages in a room (including your own), or wait for the next one

Shared CLI conventions (credential and store paths, read-only commands, known errors): references/cli-conventions.md.

Where things are stored

matrix-commander's credentials (credentials.json, which holds an access token) and encryption store live in ${XDG_CONFIG_HOME:-~/.config}/matrix-commander/. The skills always pass these paths explicitly, because matrix-commander otherwise writes them into the current directory.

Installation

claude plugins install matrix-client@danielrosehill

Status

v1.1 (2026-11-17): setup, login, rooms, send, read — each tried against a live matrix.org account. Not yet tested: reading encrypted rooms from a freshly verified CLI device.

Details

Marketplace
danielrosehill/Claude-Code-Plugins
Source
danielrosehill/Matrix-Client-Plugin
Author
Daniel Rosehill
Category
Personal Productivity
License
MIT

More from danielrosehill/Claude-Code-Plugins

All 264

Similar to matrix-client

More Productivity & Planning