Experimental matrix support

README.md

@@ -1,10 +1,10 @@
 # TellMe
 
-A server and client notifications system written in Python that alerts you of events via SimpleX chat.
+A server and client notifications system written in Python that alerts you of events via SimpleX chat or Matrix.
 
 ## Overview
 
-TellMe monitors for events (completed processes, server uptime, etc.) and sends notifications through a built-in server to SimpleX chat over websockets. Starting from version 2.2, TellMe supports [GoAlert](https://goalert.io) messages natively.
+TellMe monitors for events (completed processes, server uptime, etc.) and sends notifications through a built-in server to SimpleX chat or Matrix over websockets. Starting from version 2.2, TellMe supports [GoAlert](https://goalert.io) messages natively.
 
 ## Client Features
 
@@ -13,21 +13,59 @@ TellMe monitors for events (completed processes, server uptime, etc.) and sends
 - **Watch commands**: `-w "command"` - Run a command periodically and notify on output
 - **Ping hosts**: `-P <host>` - Monitor host availability until it's reachable
 
-## Setup
+## Server Setup
 
-1. Configure the client in `~/.config/tellme/config.json`:
-```json
-{
-  "url": "http://your-server:8000",
-  "webhook": "your-webhook-name"
-}
+### Installation
+
+```bash
+cd server/src
+pip install -r requirements.txt
 ```
 
-2. Run the SimpleX CLI chat as a daemon.
+### Configuration
 
-3. Configure `/etc/tellme/hooks.yml` to map webhooks to SimpleX chatrooms.
+1. Configure hooks in `/etc/tellme/hooks.yml`:
+```yaml
+2345555XE:
+  transport: "simplex"
+  target: "#Bottest"
+```
 
-4. Run the server and use the client CLI to send notifications.
+Supported transports: `simplex`, `matrix`
+
+2. (Optional) Configure Matrix credentials in `/etc/tellme/config.yml`:
+```yaml
+matrix_homeserver: "https://matrix.org"
+matrix_access_token: "syt_your_token_here"
+matrix_user_id: "@yourbot:matrix.org"
+```
+
+#### Obtaining a Matrix Access Token
+
+**Via Element Web (easiest):**
+1. Log into Element (https://app.element.io or your homeserver's Element instance)
+2. Go to **Settings** (gear icon) → **Help & About**
+3. Scroll to **Access Token** → click "Reveal Access Token" → copy it
+
+**Via Matrix API (curl):**
+```bash
+curl -X POST "https://your-homeserver.url/_matrix/client/v3/login" \
+  -H "Content-Type: application/json" \
+  -d '{"type":"m.login.password","user":"@youruser:homeserver","password":"yourpassword"}'
+```
+The response includes `access_token`.
+
+**Important:**
+- Use a dedicated bot account, not your personal one
+- Keep the token secure (don't commit to git)
+- Revoke it in Element settings if compromised
+
+3. Run the SimpleX CLI chat as a daemon (for SimpleX transport).
+
+4. Start the server:
+```bash
+python tellmesrv.py
+```
 
 ## Ansible