Skip to documentation
Documentation
Documentation
OverviewInstallationQuickstartYour first dayYou were sent a linkWorking with a customerConfigurationTroubleshootingFAQGlossary

Usage

Terminal interfaceCLIStatuslineDashboardAnalytics

Collaborate

DocumentsLessonsSession sharingPicking up tomorrow and handing work overFrom your phoneSession linksSession messagingAsksAsks privacy fact sheetFeedbackEmail from crewkitBlueprintsAgent identitiesMCP server

Configure

AgentsSkillsSkill and agent security scanningRulesCommandsInheritancePlaybooksExperimentsHooksCapture modesSensitive sessionsData residencyTeamSettings mapIntegrations

Workspaces

WorkspacesSet up a workspaceFix a ticket end to endShip a feature with approvalHand off work and set agent settings

API Reference

API OverviewAuthenticationSessions APIResources APIOrganizations APIProjects APIPlaybooks APIExperiments API
Need a hand?Find an answer in troubleshooting.
Loading docs…
CREWKIT / DOCUMENTATION

Session messaging

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 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), 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.

Session links

How your running sessions link and message each other, where crewkit asks for your answer, who sees your live sessions, and what crewkit keeps.

Asks

What an Ask is, who does each step from draft to Decision, how to ask people outside your organization, and what your agent sessions read.

On this page

Turning it onLevels, for adminsWriting to a colleagueThe brakesLabels and holdsYour held inboxAlertsPause and stopFor organization adminsSession links: off, pilot or onStop Session messagingWhen someone leavesAudit eventsWhere the data goesThe audit key
LevelWhat it allows
1A teammate's messages reach your session without pairing. A message is delivered only into a session that asks before acting, at your next prompt.
2Messages 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.
3An 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 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.
  • 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

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:

SignalWhenDefault
sender_budgetA 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_exhaustedA Room's budget, or the receiver's unread budget, paused it.on
risk_holdA 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

ValueWhat it means
OffNo session in the organization can link or message another.
PilotOnly sessions on the projects you list can link and message each other.
OnSessions 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.

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:

StoreWhat it holdsHow longWho can read it
Messages in flightEach 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 recordWho 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 copiesA 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 conversationThe 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 eventsWho 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.