Session messaging

Name a session with @ in your prompt, and the agent can read it, message it, or start a new session.

What session messaging does

Sessions are isolated from each other by default. Session messaging lets one session's agent read another session, send it a message, or start a new session that has its own transcript and keeps running after the current turn ends.

How sessions get connected

Connection is automatic. When you name a session with @ in your prompt, both ends are connected on the spot, effective on that same turn. A session an agent creates with start_session is connected too. Sessions that are not connected do not appear to other agents and cannot receive messages.

Naming a session in your own prompt

Type @ in the composer and pick a session from the "Sessions" tab. Each row shows its title, the agent running it, and whether it is running, idle, or a terminal session. Picking one writes @session[the session's name] into your draft. Up to three sessions are expanded per message.

A mention only names the session; Enter still runs a turn in the session you are in. Whether the agent reads the named session, messages it, or waits for it to finish depends on what you write around the mention.

“Read where @session[Login rework] has got to before we change anything here.” — the agent reads it and reports back.
“Tell @session[Login rework] that the field is now tenant_id.” — the agent writes and sends the message itself.
“Watch @session[Login rework] and tell me when that turn is done.” — the agent waits until that turn finishes.

Click a mention in a sent message to jump to that session. If it has been renamed or deleted, Mirasim says it cannot find it.

Tools the agent gets

In a connected session, the agent gets these tools:

What each one is for

Tool	What it does
list_sessions	Lists the connected sessions it can reach, with their state. Shows the current workspace by default; asked for all, it also lists other workspaces and your sessions in other spaces and on other computers.
read_session	Reads a summary of another session's last four turns (up to 2KB) and whether it is still running. With the wait option it returns as soon as that session's turn finishes, or after five minutes reports that it is still running.
send_session_message	Sends a message to another session, or replies to one it received. Up to 8KB of text; returns how the message was delivered.
read_session_message	Fetches the full text of a message it sent or received, by the message's id.
start_session	Starts a new session with a chosen agent, model, reasoning level and opening task. It does not block; the new session's reply comes back as a message.

How a message is delivered

Delivery depends on what the target session is doing at that moment.

The target's state decides the delivery

Target state	What happens
Idle, or its last turn has ended	A new turn starts there right away, with the message as the prompt.
Running, on an agent that takes mid-turn input	It joins the running turn at the next step, without interrupting a tool call in progress.
Running on an agent that does not, or waiting on a question to you	It is held until the next turn boundary, for up to five minutes, then expires with a notice.
Not connected	Refused.
A terminal (TUI) session	Can be read, but cannot receive messages.

A received message is shown with the session it came from, never as something you said. Click the source to jump to that session. If a message expires or fails to deliver, the sending session shows it.

Limits and the message log

Fixed bounds

Send rate: A session can send up to 30 messages in a burst, then one more every two seconds. The same text to the same session within 30 seconds is dropped as a duplicate.
Chain depth: A chain of relayed messages stops at 24 hops. Any human input resets the count.
Ping-pong breaker: If two sessions exchange more than 12 messages within five minutes with no human input on either side, that pair is cut off and the interface shows it.

Every message is recorded locally under ~/.mirasim/messages/: who sent it to whom, the text, and how it was delivered. Files are split by month, kept 90 days, and never uploaded.

Reading the message ledger

# the last few messages this month, as they were recorded
tail -n 5 ~/.mirasim/messages/msgs-<YYYY-MM>.jsonl

# everything one session sent or received
grep '<sessionKey>' ~/.mirasim/messages/msgs-<YYYY-MM>.jsonl

Something wrong or missing on this page? Tell us