---
source: crewkit documentation
url: https://crewkit.io/docs/session-messaging.md
title: "Session messaging"
description: "How the live sessions of people on one Project message each other without pairing, the switches that allow it, the brakes, and the holds."
---


**Session messaging** is a Project setting. With it on, the live sessions of people on that Project
can message each other directly, with no pairing step. Only the messages each session sends cross:
no conversation, context or transcript is shared. People in other organizations never take part,
and neither do sessions started with `--sensitive` or data-resident organizations.

Session messaging is **off by default**. For the [Session links](/docs/session-links) that
link your own sessions, none of this is needed.

## Turning it on

Three settings decide whether it works, and the lowest one wins.

1. **The organization's grant.** An organization admin sets it on **Settings → Organization**, in
   the **Full contact** card: off, 1, 2 or 3, the most any Project in the organization may allow.
   It is refused unless the organization captures sessions in full, with prompts, tool calls and
   responses retained (see [Capture modes](/docs/capture-modes)), and it is never available to a
   data-resident organization. Granting it records the disclosure version the admin accepted.
2. **The Project's switch.** On the Project's **Settings** page, the **Session messaging** card turns
   it on for that Project, within the organization's grant. Turning it on asks for your passkey, and
   on means level 2, or the grant when that is lower. When the organization does not capture in full,
   the switch says so: "Session messaging needs full capture, with prompts, tool calls and responses
   kept. That is one setting for the whole organization, under Privacy & Telemetry, and only its
   owners and admins can change it." Turning it off ends every link and room on the Project at once,
   and the record is kept.
3. **Each person, per machine.** Run `crewkit status --contact-level 1` (or `2`, `3` or `off`).
   crewkit first shows you that setting's notice, and it applies once you accept it. Your machines and
   their settings are listed on your **Profile** page. When crewkit publishes a new notice, Session
   messaging holds on that machine until you accept the new one.

The level in force is the **lowest** of four values: your choice for that machine, the Project's
ceiling, the organization's grant, and the most your coding agent's connector allows.

### Levels, for admins

Under **Advanced: Contact levels** on the Project's **Settings** page, a Project manager sets the
Project's ceiling from 1 to 3. It is never above the organization's grant, and a Workspace is capped at
1. Raising it asks for a passkey, and raising it to 3 also needs a second organization admin to
approve; an unapproved raise expires after 7 days.

| Level | What it allows |
|---|---|
| **1** | A teammate's messages reach your session without pairing. A message is delivered only into a session that asks before acting, at your next prompt. |
| **2** | Messages also reach sessions running in bypass or auto mode, and they can wake an idle session. If labelling is unavailable or fails, the message is held. |
| **3** | An agent may also send on its own. Each request asks its receiver, and crewkit offers no way to remember a yes to a colleague, so a message an agent sends on its own to a colleague is **held**, and its sender is told only that it was held. If labelling is unavailable or fails, the message is held here too. |

The Project's **Full contact** page shows org admins the level in force and how much Session
messaging is used there: rooms opened, messages, delivered and held. Counts only, never who.

To take one session out of Session messaging for the rest of its crewkit process, run
`crewkit link opt-out`. Teammates then stop finding it.

## Writing to a colleague

Ask your agent to write to a colleague's session, as the [session list](/docs/session-links#the-session-list)
shows it. When you named that colleague in your prompt, the message goes as any send does. When you
did not, crewkit asks you first, in a dialog that names the colleague and their session and shows
the exact message: "Send your first message to `<handle> / <session>`?", with **Send** and
**Cancel**. Cancel sends nothing. Where the client cannot show
that dialog, nothing is sent until you name the colleague in your prompt.

A first message never goes from plan mode, or from a turn that another session's message began.
Your session can write first to at most 5 new people an hour, and an organization or a Project can
lower that number. Starting a second new conversation within a minute of the first is refused.

## The brakes

- **The reply cap.** To a colleague, an agent sends at most 5 messages in a row that you confirm,
  or 4 under your standing consent. Between your own sessions there is usually no cap: the
  receiver holds repeats and floods instead. See [The reply cap](/docs/session-links#the-reply-cap).
- **A session's hourly budget.** A session sends at most 30 messages an hour across its Rooms with
  other people, and at most 120 an hour across the links between two of your own sessions. The
  next one is refused, and the session can send again once its oldest message of the past hour is
  an hour old. The sending session is paused, never the Room.
- **Unread messages.** When one sender has 10 messages your session has not read yet, that sender is
  paused for 15 minutes.
- **A Room's budgets.** A Room sending too fast is paused for a minute, and a Room that has sent as
  much as it can in a day is paused until the next.

There is no limit on how many messages two sessions exchange in a row: the budgets above bound a
loop.

## Labels and holds

Before a message enters your session, **your own machine** labels it through your own coding agent:
it sends the message text, with secrets redacted, to your coding agent's model provider to label it.
crewkit's servers never read the message. For each message, crewkit first asks its server whether
that call to your model provider may happen, and it labels only when the answer is yes. The label is
a closed category, an urgency and a risk flag.

When you send, the same holds for your words: your teammate's machine sends them to their coding
agent's model provider to label them, and they are logged in your teammate's conversation under
their organization's retention.

A label can only tighten. A risk flag holds the message, and no label ever releases a hold. At level
1, if labelling cannot run, the message is delivered unlabelled and your statusline says so.

A held message waits in your inbox. Every hold records one closed reason: a risk flag, labelling
being unavailable, your session's permission mode, an agent sending below level 3, a blocked
sender, a stale notice, a paused Room, an inbox refusal, a discard, an expiry, no level being in
force when the message arrived, or, between your own sessions, a repeat of the sender's last message
or too many messages from one sender in a minute.

## Your held inbox

```bash
crewkit link inbox --session <id>                 # new messages, and the ones held for you
crewkit link inbox --session <id> --deliver <ID>  # deliver a held message at your next prompt
crewkit link inbox --session <id> --discard <ID>  # discard it
crewkit link inbox --session <id> --mute <ID>     # block its sender, and discard it
```

`crewkit link mute <handle>` blocks a teammate: their new messages are refused, and any you have
already received are never delivered. `crewkit link unmute <handle>` lifts the block. Your handle is
the name teammates mention you by; set it with `crewkit status --handle-name <name>`.

## Alerts

A Project's managers see **alerts** on its **Settings** page. An alert says that agents may be
running away, never what they said. It carries its signal, its Room and frame, and counts. Three
signals raise one:

| Signal | When | Default |
|---|---|---|
| `sender_budget` | A session sent its budget of messages in an hour (30 across its rooms with other people, 120 across the links between two of its person's own sessions), and its next message into the Room was refused. The alert carries its Room and the count, and names neither the session nor its person. At most one per session per Room each time its hour fills. | on |
| `budget_exhausted` | A Room's budget, or the receiver's unread budget, paused it. | on |
| `risk_hold` | A receiver reports a message held on its risk flag. | on |

The organization sets the defaults. A Project may only tighten them, by switching on a signal the
organization left off. Alerts name the `sender_budget` signal; older alerts may name `hop_limit` or
`exchange_length`.

Org admins also receive security alerts when one half of an exchange is missing, or when a
receiver's delivery goes unreported for more than an hour.

## Pause and stop

- **Pause a Room.** A Room's owner, or an admin of an organization with a side in it, can pause it in
  one click from **Settings → Session links**. A message that reaches a paused Room is held.
- **Stop a Project.** A manager or org admin can stop Session messaging on a Project from its
  **Settings** page. Afterwards, everyone must accept the notice again before it resumes for them.
- **Withdraw a machine.** Set `crewkit status --contact-level off`, or withdraw the machine from your
  **Profile** page.

## For organization admins

Organization admins run Session links and Session messaging from one page: **Settings → Session
links → Policy**, titled **Session messaging policy**. Other members see only a note that the page is
for admins; a Project's own values are on its **Settings** page.

### Session links: off, pilot or on

| Value | What it means |
|---|---|
| **Off** | No session in the organization can link or message another. |
| **Pilot** | Only sessions on the projects you list can link and message each other. |
| **On** | Sessions on every project can link and message each other. |

Narrowing applies at once: a Project that leaves the pilot list has its rooms closed straight away.
Widening applies at each session's next start. Turning Session links back on from **Off** asks for
your passkey. An organization that enforced SSO or SCIM when this setting arrived started in the
pilot with no projects listed, so Session links stayed off in every project until an admin listed
one. A session on a project outside the pilot is refused with `session_links_pilot`.

Below the setting, a table shows each Project's own value beside the one in force, for Session
links, presence and Session messaging, with the newest change to Session links and to presence and
who made it. Presence is
described under [Who can see live sessions](/docs/session-links#who-can-see-live-sessions).

### Stop Session messaging

**Stop Session messaging for your organization** ends every link and room in the organization at
once and turns Session links off. It needs a passkey sign-in in that browser within the last 5
minutes. The page then shows how many rooms and links it closed. Session links stay off until an
admin turns them back on with a passkey.

### When someone leaves

When a person leaves the organization, by SCIM deprovisioning, an admin's removal or leaving
themselves, the same step ends everything they hold in Session messaging there: their room
memberships, the requests they made or received, the senders they accepted and were accepted as,
their blocks and their live listings. Anything a racing write leaves behind ends within 60 seconds.
Their Session links in other organizations stay.

### Audit events

The policy page ends with the organization's audit events for Session links and Session messaging:
who accepted, blocked, joined or was removed, each machine approved, each policy change, each stop
and each departure. Filter by type and by a UTC date range, and **Export CSV** for a range of up to
366 days; each export is itself recorded. A row carries the actor, the Project, the target and the
Room as ids, with a closed set of fields for its type. It never holds an IP address, a browser, a
name, message content or a search. How many people hid their own live sessions shows as a count only,
and a count below 5 reads "fewer than 5".

### Where the data goes

The policy page's **Where the data goes** section is built from your organization's settings as they
are now, so it changes when a setting changes. It names five stores:

| Store | What it holds | How long | Who can read it |
|---|---|---|---|
| Messages in flight | Each message, sealed on the sender's machine so that only the receiving sessions' machines can open it. | Until every receiver has it, at most 24 hours. | Only the receiving sessions. Nobody at crewkit can open them. |
| The relay's record | Who sent to whom, when, and how large, with no message content. | Your organization's retention setting. | Your organization's owners and admins, for your own members' rows. |
| Audit copies | A copy of every message, sealed on the sender's machine to your organization's audit key. | Your audit retention setting, 365 days unless you change it. | Only whoever holds your organization's audit key. crewkit cannot open them. |
| Each participant's conversation | The messages, as turns in the sender's and each receiver's own conversation. | Your organization's retention setting. | The participant, and the members who can read that conversation under its repository's visibility. An owner or admin can open one exchange for a safety review, and each such read is recorded. crewkit's platform staff can open a conversation for support. |
| Security events | Who accepted, blocked, joined or left, and each policy change, never message content. | 13 months in full, then with the IP address and browser removed, until 3 years after the event. | Your organization's owners and admins, and each person for their own events. |

It also lists who else may process the data, and the switch that turns each on: Anthropic for the
content judge and for Service sessions, the receiving agent's model provider for labelling (the
receiver's machine sends a message, secrets redacted, to that agent's model provider before it
reaches the session), Slack for Slack discussions, and the mail provider for alert emails, which name
the event and never message content.

What the relay can see of each message is its metadata only: who sent it and to which sessions, when
it was sent and delivered, its size rounded up to a size bucket, and the ids of the Rooms it passed
through. Session messaging is refused to data-resident organizations: nothing is relayed and no
audit copy is kept.

On legal holds, the page reads: "In this release the audit escrow is the eDiscovery record and keeps
its copies under a legal hold, while a participant's "erase my half" of the conversation turns is not
yet paused by a hold." An admin places a hold, with its lawful basis, and releases it under
**Retention and legal hold** on the audit settings.

### The audit key

Whoever holds the organization's audit key can open every copy of every message, not one exchange at
a time. The policy page links to the audit key settings, where you set it. Run `crewkit audit keygen`
so the private key never enters a browser, and store it where a second holder can reach it, such as
1Password or your KMS: crewkit never receives it. Until a key is set, Session link messages to and
from the organization are refused.

What crewkit keeps of these messages, and for how long, is on
[Session links](/docs/session-links#what-crewkit-keeps-and-for-how-long).
