Events

Blixel records an event each time something happens: a call is transcribed,
you join or leave a room, someone else joins, a request goes to an agent.
Hooks run on these events, and blixel event watch prints
them.

Event types

Event	When
`transcript.started`	Transcription of a call began.
`transcript.ended`	A call's transcript was finished and will not change: you left, quit or switched rooms.
`meeting.joined`	You joined a room. A reconnect is not a new join.
`meeting.left`	You left a room: you left, quit, switched rooms or lost access.
`participant.joined`	Someone else joined the room you are in. Not written for people already there when you joined.
`participant.left`	Someone else left the room you are in. Not written for people still there when you leave.
`handoff.sent`	You sent a request to an agent, yours or someone else's. Written when you send it, whatever happens to it next.
`handoff.received`	Blixel accepted a request for your connected agent, from someone in the call or from you. Written before it is accepted, discarded or delivered.

blixel event types lists them with what each one carries.

What an event looks like

An event is one line of JSON:

{"after":4812,"at":"2026-10-10T09:31:02.114Z","data":{"transcript_id":312},"id":4812,"room_id":"9f…","subject":"transcript:312","type":"transcript.ended"}

Field	Meaning
`type`	The event type.
`id`	A whole number, never reused. Later events have larger ids.
`subject`	What the event is about. Every event about one thing shares it: a transcript's `transcript.started` and `transcript.ended`, or one meeting's `meeting.joined` and `meeting.left`.
`at`	When it happened, in UTC.
`room_id`	The room, as `blixel room list` names it, or `null`.
`data`	Ids for the event's type, below.
`after`	Where to resume just past this event. It equals `id`.

What each event carries

data holds ids, never names, text or chat. Use them with other blixel
commands to get the details, which may have changed or been deleted since.

Events	`data`
`transcript.started`, `transcript.ended`	`transcript_id`. Get the transcript with `blixel transcript export <id>`.
`meeting.joined`, `meeting.left`	`meeting_id`, new for every join, as `blixel room current` shows it.
`participant.joined`, `participant.left`	`meeting_id`; `participant_sid`, the person's connection, new each time they join; `participant_identity`, who they are, or `null` when the server gave none.
`handoff.sent`	`meeting_id`; `target_identity`, whose agent it went to; `source`.
`handoff.received`	`meeting_id`; `sender_identity`, who sent it; `connection_id`, the agent connection, as `blixel agent status` shows it; `provider`, `claude` or `codex`; `source`.

source is how the request was made: spoken, typed, or mixed (spoken,
then edited or added to by typing). A request's text is never in an event.

Identities are opaque ids, not names. A request writes handoff.sent on the
sender's Mac and handoff.received on the agent owner's Mac, with the same
subject.

Limits

If Blixel crashes or is force quit during a call, no transcript.ended or
meeting.left follows, then or later.
Events don't always come in pairs. Someone already in the room when you
joined has a participant.left but no participant.joined.
Events of different types come in no fixed order. Leaving a room writes
meeting.left and transcript.ended in either order.
Blixel keeps events for 90 days.

Watch events

blixel event watch --type transcript.ended
blixel event watch --type participant.joined --room <room-id>

blixel event watch prints each event as it happens, one line each, until you
stop it. Name every type you want; there is no "all events". It reads the
events on disk, so it works with Blixel closed, though events happen only while
Blixel is open.

The first line has the type watching. To resume later without missing
anything, pass the after of the last line you finished as --after. See
Script the CLI.