README.md

Matrix Channel Configuration Guide

1. Example Configuration

Add this to config.json:

{
  "channels": {
    "matrix": {
      "enabled": true,
      "homeserver": "https://matrix.org",
      "user_id": "@your-bot:matrix.org",
      "access_token": "YOUR_MATRIX_ACCESS_TOKEN",
      "device_id": "",
      "join_on_invite": true,
      "allow_from": [],
      "group_trigger": {
        "mention_only": true
      },
      "placeholder": {
        "enabled": true,
        "text": "Thinking..."
      },
      "reasoning_channel_id": "",
      "message_format": "richtext"
    }
  }
}

2. Field Reference

Field	Type	Required	Description
enabled	bool	Yes	Enable or disable the Matrix channel
homeserver	string	Yes	Matrix homeserver URL (for example https://matrix.org)
user_id	string	Yes	Bot Matrix user ID (for example @bot:matrix.org)
access_token	string	Yes	Bot access token
device_id	string	No	Optional Matrix device ID
join_on_invite	bool	No	Auto-join invited rooms
allow_from	[]string	No	User whitelist (Matrix user IDs)
group_trigger	object	No	Group trigger strategy (mention_only / prefixes)
placeholder	object	No	Placeholder message config
reasoning_channel_id	string	No	Target channel for reasoning output
message_format	string	No	Output format: "richtext" (default) renders markdown as HTML; "plain" sends plain text only

3. Currently Supported

• Text message send/receive with markdown rendering (bold, italic, headers, code blocks, etc.)
• Configurable message format (richtext / plain)
• Incoming image/audio/video/file download (MediaStore first, local path fallback)
• Incoming audio normalization into existing transcription flow ([audio: ...])
• Outgoing image/audio/video/file upload and send
• Group trigger rules (including mention-only mode)
• Typing state (m.typing)
• Placeholder message + final reply replacement
• Auto-join invited rooms (can be disabled)

4. TODO

• Rich media metadata improvements (for example image/video size and thumbnails)