Matrix

Matrix is an open-source, decentralised communication protocol. OMD Cleo uses a Matrix homeserver as both a reactive chat channel and as the delivery target for workflow-triggered messages.

How it works

The Cleo agent joins Matrix rooms and responds to messages using the Matrix SDK. It can:

React to any message sent to a room it is a member of.
Create a new room for a workflow run and invite the target users.
Reuse an existing room if a user already has an active room for the same workflow.

Setup

Add matrix to ENABLED_CLIENTS:

ENABLED_CLIENTS=matrix

Required environment variables:

Variable	Description
`MATRIX_HOMESERVER_URL`	URL of the Matrix homeserver (e.g. `https://matrix.optimizemyday.ai`)
`MATRIX_USER_ID`	Full Matrix user ID of the bot (e.g. `@cleo:optimizemyday.ai`)
`MATRIX_ACCESS_TOKEN`	Access token for the bot user

Message rendering

Cleo sends Matrix messages as formatted HTML (using the m.room.message event with format: org.matrix.custom.html). Markdown in the agent's response is converted to Matrix-compatible HTML automatically.

Reactive mode

When a user sends a message to a room the bot is in, the agent processes the message and replies in the same room. The conversation history is preserved across turns within the same room.

Workflow mode

When a workflow is triggered via the HTTP API, the agent:

Finds or creates a Matrix room for the given (user_ids, workflow_id) combination (or always creates a new room if new_room: true).
Invites the specified users.
Delivers the workflow output as one or more messages in that room.

Tool confirmation

For tools that modify data (e.g. updating a task), the agent can send a confirmation request as a Matrix reaction or message. The user reacts or replies to approve or reject the action.