Streaming Responses
MindRoom streams agent responses to Matrix by progressively editing a single message, so users see text appear as the model generates it. This page covers when streaming is used, how to tune or disable it, how streamed messages show tool calls, completion, cancellation, and errors, and how oversized responses are delivered.
How It Works
- MindRoom sends an initial message showing a
Thinking...placeholder until text arrives. - As text arrives, MindRoom edits the same message with the accumulated content.
- When the response finishes, a final edit holds the complete text.
When a response is not streamed, the placeholder is replaced with the complete response in a single edit. Agents also show a typing indicator while they work on a response.
Live Updates
When the homeserver relays live updates, as MindRoom's Tuwunel fork (mindroom-tuwunel) does for mindroom.chat, hosted MindRoom, and mindroom-stack, MindRoom Chat shows a streamed reply about ten times a second, including its tool calls, worker progress, and reasoning, without editing the message each time.
While a tool such as shell runs, MindRoom Chat also shows the last lines of its output under the call, with credentials masked as in tool results; the message keeps only the tool's result, and team replies do not show it.
The message itself is then edited only every update_interval seconds (5 by default) and once at the end, so Element, bridges, and other clients show the reply in steps of about five seconds and end with the same final message.
A reply that grows too large for a live update, as a very long reply with many tool calls can, switches to the progressive edits below for the rest of the reply.
Live updates are encrypted like the reply in an encrypted room.
They reach only accounts on the agents' homeserver; people on other homeservers see the message edits.
MindRoom Chat opened while a reply is streaming shows the last edit until the next live update, at most five seconds later.
A reply that is stopped or ends with an error keeps the text of its last edit, so up to update_interval seconds of text MindRoom Chat showed live can disappear above the note.
A homeserver relays them when its /_matrix/client/versions lists io.mindroom.ephemeral_opt_in, which the fork does unless its mindroom_ephemeral_events_enabled option is off; with any other homeserver every client sees the progressive edits below.
MindRoom Chat's Sub-agents panel uses the same mechanism: it shows each running subagent and Dynamic Workflow participant with its text and tool calls as they happen, then how it ended.
Tool call details appear there only when the reply that started the subagent shows its tool calls.
It needs a homeserver that relays live updates, and is empty when they are off or the conversation is not in a Matrix room.
Set defaults.streaming.live_frames: false to turn live updates off, so every client sees the progressive edits below, and the Sub-agents panel shows nothing for subagents that start afterwards.
Configuration
Streaming is enabled by default.
These settings are global-only under defaults and cannot be overridden per agent.
defaults:
enable_streaming: true # Set false to disable progressive edits
streaming:
update_interval: 5.0
min_update_interval: 0.5
interval_ramp_seconds: 15.0
max_idle: 2.0
live_frames: true
| Field | Type | Default | Description |
|---|---|---|---|
enable_streaming |
bool | true |
Stream responses via progressive message edits. When false, the placeholder is replaced with the complete response in a single edit. |
streaming.update_interval |
float, > 0 | 5.0 |
Steady-state seconds between edits. |
streaming.min_update_interval |
float, > 0 | 0.5 |
Seconds between edits at the start of a response. |
streaming.interval_ramp_seconds |
float, >= 0 | 15.0 |
Seconds over which the interval ramps from min_update_interval to update_interval. Set 0 to use update_interval from the start. |
streaming.max_idle |
float, > 0 | 2.0 |
When no new text has arrived for this many seconds, the buffered text is shown with the next streaming update. |
streaming.live_frames |
bool | true |
Send live updates when the homeserver relays them, and edit the message only every update_interval. |
Edits also come sooner than the interval once enough new text has accumulated, and a tool-call marker appears as soon as the tool starts.
While live updates run, edits come only every update_interval, and the other timing settings have no effect.
Raise update_interval to reduce load on the homeserver, or lower it for smoother updates.
Presence-Based Streaming
Even when streaming is enabled, MindRoom streams a response only when the user who sent the message is online or unavailable; for an offline requester, the placeholder is replaced with the complete response.
Everyone in the room sees the same edits.
If the presence check fails, for example because the homeserver has presence disabled, MindRoom does not stream.
A reply that continues after a restart keeps the part it already showed; the rest streams even when streaming is off or the requester is offline, except in a silent schedule's run.
When no requester can be identified, MindRoom streams.
Presence
Running agents appear online (or unavailable when idle) and offline when stopped or disconnected.
Their presence status message shows the model, role, and tool count, for example 🤖 Model: anthropic/claude-sonnet-5-5 | 💼 Code assistant | 🔧 5 tools available.
Stream Status
Each streamed message carries its progress in the Matrix event content field io.mindroom.stream_status.
| Value | Meaning |
|---|---|
pending |
Initial message of the response |
streaming |
Response is still being generated |
approval_pending |
Response is paused until someone approves or denies a tool call (see Tool Approval) |
completed |
Response finished, including one that ends by reporting an error, such as a provider failure, whether or not part of the answer came first |
cancelled |
User stopped the response |
error |
MindRoom could not finish or deliver the response, for example because of a restart or a failed delivery; a response cut short ends with a note that says why (see Cancellation and Errors) |
To confirm a response finished, inspect the latest io.mindroom.stream_status in a client or event view that shows event content.
MindRoom never appends an ellipsis to generated text, and clients may draw their own progress indicators, so a trailing ellipsis is not a progress signal.
Tool Calls During Streaming
When an agent calls tools, MindRoom shows inline markers in the message text:
The number in brackets counts tool calls within the message, and io.mindroom.tool_trace.events[N-1] in the event content holds the tool name, argument preview, result preview, and tool_call_id for call [N].
A completed call that did not succeed (it errored, was refused or denied, or was cancelled or interrupted) also carries is_error: true, and its result preview says why; the key is omitted on a call that succeeded and on a started one, in live frames and the final event alike.
A secret request card (io.mindroom.secret_request) that a reply's tool call posted names that reply's event (response_event_id) and the call (tool_call_id), so a client can draw the card at the call's line; a call made through the CLI from a Bash call has its own line, which the card names.
Tools that start in quick succession appear together in one edit.
Markers and tool-trace metadata are shown by default; to hide them, set show_tool_calls: false on one agent or under defaults for every agent that leaves it unset (see Agent Configuration).
With tool calls hidden, the agent still shows typing activity, and a tool that needs an isolated worker may show generic progress such as Preparing isolated worker... 17s elapsed. without naming the tool.
Reasoning
When a model reasons before or between parts of its answer, as with Anthropic extended thinking, OpenAI reasoning summaries, Gemini thinking, or <think> blocks, a streamed reply shows that reasoning to everyone in the room.
MindRoom Chat shows it live above the answer and, once the reply finishes, as a collapsed "Thought for N s" block, where N is how long the model reasoned.
The final message keeps it in io.mindroom.reasoning; it is never part of the answer text or the agent's history.
The final message also keeps where each reasoning segment began (segments: UTF-16 start in text, after_tool, duration_ms), so clients can show it between the tool calls; segment durations add up to the total unless long reasoning was cut, which drops the later segments.
Live frames carry the same list without durations.
Set show_reasoning: false on an agent, or under defaults, to keep reasoning out of the room.
Reasoning can describe tool calls that show_tool_calls: false hides, so set show_reasoning: false as well to keep them out of the room.
Long reasoning is shortened on the final message so the reply stays one ordinary message; replies that are not streamed, team replies, and replies split into several messages (large_message_strategy: split) keep no reasoning, and a reply that paused for a tool approval shows its reasoning only until the pause and keeps none on its final message.
Cancellation and Errors
Users can cancel an in-progress response by reacting with 🛑 on the message being generated (see Stop Button).
Tool calls running in a worker, such as run_shell_command or run_python_code, stop with it, apart from the exceptions listed there.
The partial text stays in the message, followed by a note explaining how it ended:
| Note | Cause |
|---|---|
**[Response cancelled by user]** |
The user stopped the response. |
**[Response interrupted by service restart]** |
MindRoom restarted while the response was being generated; the reply continues below the note once MindRoom is back, or ends there if nothing is left to continue. |
**[Response interrupted: agent restarted to apply a config change]** |
A config.yaml edit restarted this agent (for example, its tools changed) while the response was being generated; MindRoom itself kept running, and the reply continues below the note once the agent is back, or ends there if nothing is left to continue. |
**[Response interrupted]** |
The response was interrupted for another reason. |
**[Response interrupted by an error: <error description>]** |
MindRoom could not finish the reply; the description says why. |
Done. |
The agent finished without writing an answer of its own, for example after tool calls hidden by show_tool_calls: false or after a tool posted its answer; those tool calls still ran. |
Response delivery failed. Please retry. |
Matrix refused the answer or could not take it, so the note replaces what the reply showed; send the message again for a new answer. |
Tool approval could not be started. Please try again. |
The agent paused for a tool approval, but MindRoom could not start the approval or show it in the room, so the tool did not run; send the message again. |
A crash, an orderly shutdown, or an agent restarted by a configuration or MCP change, including during an approved tool call, keeps the partial reply and its tool calls, and the agent continues it in the same message once MindRoom is back.
The agent is told which tool calls already finished, and which were still running, so it avoids repeating side effects, including calls hidden by show_tool_calls: false and calls made while streaming is off.
Nothing blocks a repeated call, so a model can still occasionally run one again.
Large Messages
A Matrix event holds at most about 64 KB, so defaults.large_message_strategy controls how a larger response is delivered.
| Value | Delivery |
|---|---|
sidecar (default) |
A preview with as much text as fits, plus the full message content attached as message-content.json (message-content.json.enc, encrypted, in encrypted rooms). |
split |
Several complete rich-text messages: the first replaces the streaming placeholder and the rest follow it in the same thread or room. |
The sidecar strategy applies to messages over about 55 KB and edits over about 27 KB, and the preview omits inline tool-trace metadata.
With split, each segment renders as standalone Markdown, text is cut at paragraph or line boundaries and never inside a fenced code block, and the segments together reproduce the full response text exactly.
Each segment carries the tool calls it shows, numbered from 1; a segment with many tool calls may show them without their input and output previews, or, when even their names do not fit, without them.
Even with split, non-text payloads, metadata that alone exceeds the size budget, and a single code block larger than one event use the sidecar.