Omniscio

Team Chat (built-in channels and direct messages) (part 3)

Part 3 of the Team Chat page: the phone client and the surfaces that sit around the core chat — the standalone phone web app and its push notifications, notification preferences, rich link previews, the project-management bridge, share-comment cross-posting, starting a Claude session from a thread, the Session Starter Bot, the media gallery and video-call backgrounds.

On this page

What it is

This is part 3 of the Team Chat (built-in channels and direct messages) page. It covers the phone client and the surfaces around the core conversation — how Team Chat reaches a phone and what web push does there, notification preferences, link previews, the project-management bridge, comments on a shared link, and the two ways a chat message can start real Claude work: a thread handed to a working session, or a channel watched by a Session Starter Bot. It closes with the media gallery and the video-call background picker.

Where to find it

The same surface as the parent page: once switched on, Team Chat appears as a built-in virtual project in the projects sidebar, with the channel and DM list in the sidebar pane and the open conversation filling the main panel. It ships dark until Settings → Lab → Team Chat is on. The parent page covers finding and enabling it.

The phone client is a separate web app reached at its own address rather than a screen inside the desktop sidebar, and the notification controls live in Settings → Team Chat notifications and on each channel's bell menu. The rest — the Media gallery entry in a conversation's More actions menu, the video-call background button, the thread's Start a session action, the Session Bot entry in a channel's right-click menu, and the Create task and Send to Mission Control actions on a message — are all inside the chat surface.

How it behaves

When something fails (desktop)

  • A failure says why, when Team Chat knows. A notice like "Could not update pin" adds the cause when the error names one: "It may have been deleted.", "Too many changes at once. Wait a moment, then try again." or "It changed while this was being saved. Try again." The cause is added in one shared place (chat-error.ts), so every Team Chat action gets it.
  • Retry where trying again can help. A failed reaction, pin, save or cancel-scheduled, a failed channel-list load, a failed search, and a failed automatic join to #general each carry a Retry button that runs the same thing again. A permission refusal, or a channel that cannot be read, gets no Retry, because a second try would fail the same way.
  • Nothing fails silently any more. Copying a message's text, saving or clearing your status, unread counts that stopped updating, workspaces that did not load, and incoming webhook messages that could not be posted each tell you so. Cancelling an upload is no longer reported as a failed upload. The status dialog closes only once the status is saved.
  • Forms check before you submit. The join dialog checks the invite code's shape (10 letters or numbers) first, Invite teammates lists non-email entries and sends only the real ones, a time typed in words is checked when you leave the field rather than on every keystroke, and Send stays off for text that is only invisible characters.

Mobile (PWA) client — the always-on phone app

Two phone paths to Team Chat. (1) Through Omniscio — the team's path (since 2026-06-28): reach your OWN desktop Omniscio from your phone over Tailscale, and its mobile web access serves the renderer — Team Chat included. This required allowing Team Chat's NAMED Firebase hosts through the web-access CSP (web-access-http-shared.ts connect-src, pinned by web-access-team-chat-csp.test.ts); it needs the desktop running (Tailscale reaches it), and on this path the desktop rings the phone for a direct message or an @-mention from every workspace you belong to (see Notification preferences below). (2) The standalone PWA — the PC-off fallback (described below).

On a phone the renderer is tuned for touch. Every Team Chat screen keeps to ONE header row under the app's tab bar: the generic project title bar is hidden on every Team Chat panel (shouldShowMobileBreadcrumb keys this on Team Chat's own project id, the same way it hides the bar for Notes and Tasks, which also draw their own headers; you leave through the tab bar's Projects tab). The channel list's header holds your avatar and the workspace switcher on the left and search, + and ⋯ on the right, with the sidebar filter as the first ⋯ item rather than a permanent row; Saved keeps its search box behind a magnifier in its header; and Needs you shows History and Mark all done as icons that keep their full names for screen readers. An open channel shows one header (a ← back chevron to the channel list, the channel name, the notification bell, and the member count) instead of stacking the workspace bar above it, message actions move to a bottom action sheet (opened by the small ⋯ beside each message, or a long-press), and the composer's formatting toolbar collapses behind a toggle (all three detailed in the feature list above).

The phone client is a separate, standalone web app (team-chat-pwa/) served by Firebase Hosting — reachable on a phone even when the desktop is OFF (it deliberately does NOT use the desktop-tethered mobile web-access bridge). It shares one data layer + one set of frozen types with the desktop (reusing @shared/team-chat/* + the Phase-0 schemas), so both behave identically; only the shell + auth differ.

  • Auth differs from desktop. The desktop signs in with a custom token minted by Main; the phone has no Main, so it does a normal interactive "Sign in with Google" web sign-in (the same Global Auth identity) and resolves the workspace from the user's own users/{uid}.organizationId. On sign-in the phone materializes the user's profile first (the same getOrCreateProfile the desktop calls, via a same-origin Hosting rewrite), so a brand-new invited teammate who opens the phone FIRST is onboarded into the workspace instead of dead-ending — with a fallback to the direct read so an existing member never regresses. No workspace → a friendly "not in a workspace yet" screen, never a blank one.
  • Web push (FCM). A service worker + Firebase Messaging register the phone's device token into organizations/{orgId}/fcmTokens/{uid} (own-doc, transactional merge, capped, never clobbering the desktop's entry) — the store the message trigger (onMessageWritten) reads to fan out push. The service worker gets the real (public) Firebase config injected at build (as /firebase-config.js), without which background push silently no-ops. Push registration also needs the build's public push certificate key (VITE_FCM_VAPID_KEY): a build deployed without it skips registering on the phone and logs that, and chat works without notifications. Foreground → in-app toast; background → a notification deep-linking to the channel. When notifications cannot be turned on, the bottom of the channel list says why and what to do (allow them in the browser or phone settings, add Team Chat to the Home Screen on an iPhone, use a browser that can show them, or tap Try again after a connection problem), instead of only a muted-bell icon. The phone never opens the notification permission prompt on its own: a phone that has not been asked yet shows a Turn on notifications button, and the prompt opens only from that tap (iPhone home-screen apps ignore a prompt that does not come from a tap). On sign-in the phone registers for every workspace in the person's list and says once which ones, and that workspaces created inside Team Chat are not covered yet.
  • Direct connections on the phone. A connection row shows an unread marker and the last message preview; the read point is kept per person on that device and only moves forward. The conversation opens at its newest message, pages in older history on request, and follows new messages only while you are at the bottom. A half-typed message stays with its own contact when you go Back, and is cleared on sign-out. Disconnect in the conversation header asks first, names the person, and leaves the conversation once it succeeds.
  • Notification controls live on the phone itself. Every channel row in the phone's list has its own bell that opens a sheet for that channel only: All messages, Mentions only, Mute, a temporary mute for 1 hour / 8 hours / 24 hours, Unmute while a temporary mute is running (with the time it ends), and Use default to fall back to your account-wide choice. The same bell sits in the open channel's header. The row's bell shows a muted glyph and speaks "muted" for a channel that is silent, so a channel that stops buzzing is visible rather than mysterious. A Notification settings entry in the sidebar footer sets the account-wide default (All messages / Mentions only / Mute) and the Hide message text in notifications choice. All of these write the same notifPrefs/{uid} document the desktop writes, one field per choice, so the phone and the desktop never disagree and a change on either shows up on the other. Nothing here turns push on or off — that stays automatic, and the note at the bottom of the list still explains it when push is unavailable.
  • Your account lives in the sidebar footer. Tap your name at the bottom of the phone's channel list to open the You sheet: change your Display name, Add, Change or Remove your photo (the picture is re-encoded on the phone before it uploads, so a photo's location data never leaves the device), and Leave this workspace. Leaving names the workspace and asks first, then puts you in your next workspace — or on the "not in a workspace yet" screen when that was your last one. The phone hides Leave this workspace for a workspace's only owner or admin and says why, since a workspace must keep one; a plain member always sees it. Before this, the footer offered only Sign out, Export data and Delete account, so getting out of a single team meant deleting the whole account.
  • A sign-in that cannot reach your workspace is never a dead end. When the workspace cannot be loaded, the phone says so and offers two ways out: Try again, which retries the workspace lookup on the spot, and Use a different account, which signs you out (clearing this device's cached chat data) so the next sign-in is free to use another account. Google's account picker is always shown on sign-in, so signing in again never silently re-uses the wrong Google account.
  • Installable. A web manifest + maskable icons + an iOS "Add to Home Screen" hint (iOS 16.4+ web push needs an installed PWA).
  • Opens the workspace you last used. If you belong to more than one workspace, the phone opens the one you last chose straight away at launch rather than showing your profile workspace first and then switching. It checks that choice against your memberships once the list arrives and falls back to your profile workspace, correcting the saved choice, if you no longer belong to it; if the list cannot be fetched, it opens your profile workspace.
  • Attach a photo or a file — and open one full size. A paperclip in the phone's composer opens its own picker, so you choose a photo from the library or take one there and then (the OS sheet offers both). The picked file uploads with a visible progress bar on its chip, can be cancelled or removed before you send (removing it deletes the uploaded bytes), and a failed upload names itself and offers Retry rather than a silent chip. The attachment rides the same message the desktop writes — one shared builder produces the attachment list, so the phone and desktop can never disagree about a message's files — and sending only a file is allowed: the body then lists the file names, because chat requires some text. An image shows as a thumbnail; tap it to open full size, tap the ✕ or the backdrop to close. The picture is fetched through the same short-lived, membership-checked link the desktop uses, so a file you no longer have access to says so instead of a broken image. Photos are shrunk on the phone before they are sent — the same treatment the desktop applies, a 2048-pixel long edge re-encoded as a high-quality JPEG — so a 12-megapixel camera picture costs a fraction of its original bytes in storage and on every later view. Files the desktop sends (PDFs, documents, videos) show on the phone as a card with the name and size.
  • Reading and sending on the phone. Files such as PDFs and videos open from the message. A conversation lands on its newest message and follows new ones while you are at the bottom, and times show a date once a message is not from today. A message still on its way says it is sending, including one queued while offline. Typed text stays with its own channel or thread until you send it (staged uploads are still dropped when you leave).
  • What you can do in a channel is shown, not discovered. If you cannot post, the message box is replaced by a read-only line, and an archived channel says so. A channel that has been deleted, or that you lost access to, says that instead of loading forever. Deleting a message with replies warns you that the thread goes too, and the message dims as soon as you confirm.
  • Threads and search say what they cover. A thread has its own replies and an honest count. In-conversation search says what it searches, and counts only the rows it shows. New messages are announced to screen readers, and per-message controls are reachable by touch.
  • Clickable web links. Bare http(s):// and www. URLs render as tappable links (open in a new tab) — the mobile mirror of the desktop's autolinking, so a shared link is clickable on your phone instead of dead text. Only real web links match; app omniscio:// deep links stay plain text.
  • Works from a keyboard. In the @mention list, the arrow keys move the highlight and Enter or Tab picks the name instead of sending the half-typed one. The message action sheet, the delete confirm, the reaction picker and the image preview take focus when they open, keep Tab inside, close on Escape and hand focus back to the button that opened them; the edit box cancels on Escape and saves on Ctrl+Enter or Cmd+Enter. On a phone, the back, header, reaction and edit buttons are at least 44 pixels square.
  • Failures you can act on. When something does not go through (a send, a reaction, a pin, opening a conversation, creating a channel), the notice names the real cause rather than blaming your connection — a message over the length limit says so and names the limit, and the connection is blamed only when the browser reports you offline. The notice is announced immediately to screen readers and stays about 8 seconds, with a Retry button where a retry makes sense. Creating a channel keeps the name you typed until the write is accepted, so "try again" is one tap instead of a retype. A message that fails to send is put back in the box. In a channel or a DM, a message the server refuses stays in the conversation marked failed, with Retry, and a notice says it was not sent. If the app hits an unexpected problem, it shows a full screen saying your sent messages are safe, with one full-width Reload button. A direct message to a connection that is still waiting for the network stays in the conversation and says it is still sending, rather than reporting a failure and handing the text back for a second copy. A new channel's form closes on the tap, so a create that is still waiting cannot be tapped twice; if the create is refused, the form reopens with the name you typed.
  • A dismissed warning leaves a sign. If live updates stop, the banner says so; dismissing it hides the banner but leaves a quiet Not updating marker with its own Refresh, so the app never looks live while serving stale data.
  • Signing out tells you if the device was not fully cleared. Sign-out normally clears this device's cached Team Chat data and its push subscription. If either could not be cleared (another Team Chat tab is open, say), it still signs you out and then says so, with what to do, in a notice that waits to be read. A sign-out that genuinely failed says so instead, and leaves you signed in. Sign-out also closes the Team Chat notifications still showing on the device, and any other open Team Chat tab switches to the clearing screen instead of offering sign-in over the old cache. If the push subscription could not be dropped in time (a slow or offline sign-out), the app drops it the next time it opens, before it registers the device for anyone else.
  • Holds no secret — only the signed-in user's own session; all authorization is server-side rules.
  • Runs for any provisioned workspace — the rules and the notify function behind the phone client are live, so a workspace gets the phone client the moment its member docs exist.
  • Load earlier keeps the whole conversation. Older messages you page in stay on screen as new ones arrive, with no gap in the middle, and an older page is always read from the server, so on a phone that is offline Load earlier offers a retry instead of saying there is nothing older.

Notification preferences

Every workspace you belong to tells you about new messages, whichever one you have selected. Your company workspace and each private space you share with family or friends raise a Team Chat notice in your Omniscio inbox — one row per conversation with a running count, plus a pop-up while Omniscio is open — for a new message in a channel you have joined or in one of your direct messages. The selected workspace only decides what Team Chat shows on screen; a message in another workspace is never held back until you switch to it. Messages that arrive while Omniscio is closed, or while your PC is asleep, show up as the same inbox row (without a late pop-up) the next time Omniscio is running, in every workspace — with how many you missed, so ten messages in #general read "#general ×10" and each conversation keeps its own row. A conversation you already read on another device raises nothing, a row you dismissed is not raised again for a message it already announced, and joining a workspace raises nothing for what was said before you joined. A channel you set to Mentions only still counts one per notice. (Contract: team-chat-notifications-contract.md a-catch-up-row-counts-what-it-catches-up-on, a-wake-re-runs-the-background-catch-up.) Your own messages, channels you have not joined and hidden agent-lane channels never raise one. A phone paired through the desktop phone link rings for a direct message or an @-mention from every workspace too, exactly as it does for the selected one, and catches up the way the desktop does: messages from while the computer was off or asleep arrive as inbox rows, and a direct message or @-mention among them rings the phone once when the computer is back, with no ring again for one you already saw. Each workspace notifies under its own workspace notification level — All messages, Direct messages and @mentions, or Nothing — which starts at All. Nothing raises no inbox notice, pop-up or phone alert for that workspace; Direct messages and @mentions raises them only for a direct message or a message that @mentions you. A choice you make for one channel or DM still wins over its workspace's level. Set it from the workspace's own menu in the switcher (right-click or long-press its tile, or ⋯ on a phone), or from the list of every workspace in Settings -> Team Chat notifications; both show the same level. A private space keeps its level, and its per-channel choices, in its own saved preferences, just like the company workspace; while those preferences cannot be read, it notifies only for direct messages and @mentions, and both places show that level and cannot be changed until the preferences load. Focus mode and Do Not Disturb quieten the pop-up whichever workspace a message came from, and the inbox row still lands, so quiet time never costs you the record; the Team Chat notices on this computer switch turns all of it off, for every workspace at once. (Contract: team-chat-notifications-contract.md every-workspace-a-person-belongs-to-notifies.)

Every workspace you belong to is watched, however many there are. There is no limit: every private space and every company workspace you are a member of — the one you signed in with and any other company that added you — is watched in the background, so a second company's messages notify you too, and its pop-ups carry its own name. Leaving a workspace, from Team Chat or from Settings, stops its notices straight away. A hiccup while Omniscio re-reads your company list or your private spaces never drops a workspace you already had: the ones on screen stay, and stay watched, until the list can be read again. Omniscio re-reads the list every few minutes, so a company workspace you are added to while Omniscio is running is watched within minutes, with no restart. Each watched workspace keeps about six live connections to the chat server open. (Contract: team-chat-notifications-contract.md every-workspace-is-watched-with-no-limit.)

Every pop-up says which workspace it came from, and clicking it takes you there. A Team Chat pop-up is titled with the workspace first, then the conversation — "Byron and Bevan · Bevan", or "Company workspace · #general" — for the workspace you have selected too, using the same name the workspace switcher shows. The inbox row keeps its usual title. With message content hidden, the pop-up is titled with the workspace and "Team Chat" ("Byron and Bevan · Team Chat") and still shows no sender or text. Clicking a pop-up brings Omniscio forward, switches to that workspace and opens the conversation, and the thread for a reply; the inbox row's Open channel and an omniscio://chat/… link (which may name a thread with ?thread=<id>) do the same. (Contract: team-chat-notifications-contract.md a-toast-names-its-workspace-and-a-click-opens-the-conversation.)

You control when Team Chat notifies you. Each workspace has its level (above) — All messages, Direct messages and @mentions, or Nothing — then you can override any single channel or DM (mute a noisy one, or follow a quiet one closely). You can also temporarily mute a channel for 1 hour, 8 hours, or 24 hours -- the mute suppresses all notifications until it expires, then the channel returns to its normal mode. This is what the desktop notification decision honors; the Cloud Function reads the same per-workspace doc (organizations/{orgId}/notifPrefs/{uid} for the company workspace, chatWorkspaces/{wsId}/notifPrefs/{uid} for a private space) and, per channel, applies your override if set, otherwise the workspace's level (a temporary mute is honored by the server too: no push is sent while it lasts). If Team Chat cannot connect on this settings page, it says so and offers Try again, rather than showing "Connecting to Team Chat" forever.

Three places set it, all writing the same doc:

  • The full control lives in Settings -> Team Chat notifications -- a level picker for every workspace you belong to, by the name the switcher shows, plus a per-channel/DM list for the selected workspace with temporary mute indicators. It's a deep-link-only section (no sidebar nav row, because Team Chat ships dark); you reach it from the channel bell menu below, and it self-gates when Team Chat isn't enabled or you're not in a workspace yet. It also carries Replies per conversation per day -- the most replies from one conversation your AGENT will be woken for in a day, blank for no limit. It sits here rather than with the agent features on purpose: replies wake your agent on every install using Team Chat, so the control must be reachable wherever Team Chat is reply watch.
  • A quick per-channel control lives in the conversation header's More actions menu as Notifications (a submenu) -- it sets THIS channel to All / Mentions only / Mute (permanent), mute temporarily (1h/8h/24h), unmute (when temp-muted, with expiry text), reset to the default, or jumps to the full settings. Its glyph reflects the channel's current resolved setting (bell / @ / bell-off), accounting for temporary mutes. Pin it from that menu to show the bell in the header row itself; on a phone the bell always sits in the header beside the menu.
  • The channel right-click context menu in the sidebar -- mute for 1h/8h/24h when not temp-muted, or Unmute (with expiry status) when temp-muted, above the existing Edit/Leave/Delete items.
  • "Hide message content in push notifications" (on by default) hides the sender and text from phone push notifications and from the desktop pop-up, which then just say "New message". It hides the text from a catch-up Inbox row too — the row raised at the next launch for a message that arrived while the app was closed — while a notice raised while the app is running still carries the real text, in the Inbox row and in Needs you → History: those are your own record on this computer. The pop-up decision is made in one place in the main process (showToastIfNew, driven by the notice's hideToastContent flag); every notice producer sends the real text. Whatever a notice shows, an @mention in it reads as the person's name, never their account id — the same rule the Needs you row follows.
  • A notice never quotes a message the conversation no longer holds. Editing the newest message, or deleting a message or a thread reply, retires the inbox notice that quoted it, in the workspace on screen and in every other workspace too. Each retire clears only its own kind: deleting a reply leaves the channel's message and reaction notices alone. The channel you are reading is skipped, because reading it already cleared its notice. A reply notice is retired only when the thread it named changed or no reply is left, so a same-thread delete that leaves another reply in place keeps the notice. The clear route takes a noticeKind of message or reply; with no kind it still clears all three, as the read path does.
  • Content-free pop-ups hide the sender and the text, not the workspace. With message content hidden, the desktop pop-up is titled with its workspace and Team Chat ("Byron and Bevan · Team Chat") instead of the sender or channel, and says "New message"; the Inbox row keeps its real title. If your notification settings cannot load, Team Chat uses a safe stand-in until they do: only mentions and direct messages notify, with content hidden, so a channel you muted stays quiet. While offline, the banner at the top of Team Chat offers Retry now, and the sticky pop-up appears only while the Team Chat panel is closed.
  • "Hide message content in push notifications" (on by default) hides the sender and text from phone push notifications and from the desktop pop-up, which then just say "New message" under a plain "Team Chat" heading instead of the channel name or the sender (so a channel or display name written to look like a warning never reaches the lock screen). It never blanks the Inbox row or Needs you → History: those are your own record on this computer, so they always show the real message text. The pop-up decision is made in one place in the main process (showToastIfNew, driven by the notice's hideToastContent flag); every notice producer sends the real text. Whatever a notice shows, an @mention in it reads as the person's name, never their account id — the same rule the Needs you row follows.

For engineers: the renderer reads + writes notifPrefs/{uid} directly via the Firebase web SDK (own-doc-write; the rules allow only {uid}). Writes are field-scoped merges (only default, one perChannel key, or one mutedUntil key, never the whole doc), so a concurrent edit can't be clobbered, and a missing/corrupt doc falls back to the safe default. The mutedUntil field is additive; legacy docs without it parse to {} (no mutes). Errors are humanized (never raw Firestore text). A prefs subscription that fails now retries instead of staying dead for the session, and until the document has been read once the desktop watcher decides on UNKNOWN_NOTIF_PREFS (mentions only) rather than the "All messages" default, so a load that never lands cannot un-mute channels the user muted. Invariants + tests: team-chat-notif-prefs-ui-contract.md (client/UI side) and team-chat-notifications-contract.md (server fan-out).

Content-free notices are governed by TWO switches that do NOT sync. The per-org Firestore notifPrefs.contentFree flag (default true) is the one the Team Chat settings page exposes as "Hide message content in push notifications". It gates Team Chat notices on every surface they are produced on this machine: the push payload, the desktop OS toast, and the Inbox row body, so with the shipped default every Team Chat notice body reads "New message" until the user turns it off. A second setting, contentFreeMobilePush in the app's own notification settings (also default true), is a SEPARATE native-app switch that governs the FCM path only. The two live in different stores (a per-org Firestore document versus local config.json), nothing copies one to the other, and they can disagree: turning content-free off in one place leaves the other unchanged. Server-side, the onMessageCreate Cloud Function coerces an absent or non-boolean contentFree to true (coercePrefs), and recipients.ts defaults a missing per-user flag the same way (?? true); a parity test pins both to the shared schema default so they cannot drift.

Team Chat on a computer you don't answer chat on

If you run Omniscio on more than one computer under the same sign-in, every running copy of the app turns a new Team Chat message into an Inbox row, a desktop notification, a Needs you entry and a Needs reply mark. That is right for the machine you actually answer chat on, and noise on the others.

Settings → Team Chat notifications → "Show Team Chat notices on this computer" is the switch that fixes it. It is on by default, and it applies to this computer only.

  • Switched off, that computer raises no Inbox row and no desktop notification for a message, a reply or an emoji reaction, shows no Needs you rows and no counts, and marks nothing as needing a reply — the sidebar row, the dot inside a conversation, the Up-next strip and Needs you → History all go quiet together.
  • The chat itself is untouched there: you can open it, read history, search, use threads, send messages and take calls exactly as before, and unread dots keep working so you can still see there is activity.
  • Switching it off also clears the Team Chat notices that computer was already holding, so the Inbox is quiet from that moment rather than from the next message.
  • Three things deliberately stay: an incoming call still rings (a call is a live event, not a message waiting on you), a "remind me later" you set on that computer still surfaces, and a pending connection request still appears because it is an approval to answer.
  • Switching it back on does not replay what arrived while it was off — those messages stay unread in their channels, and the next message raises normally.

Because it is a per-computer preference it is never carried in a settings export, so importing your settings onto another computer cannot silence it there. The invariants and their tests are in team-chat-notifications-contract.md (a-computer-can-opt-out-of-chat-notices).

When a message contains a URL, Omniscio fetches the page's Open Graph metadata and renders a rich preview card below the message — title, description, image and site name — modeled after an earlier internal prototype. In chat the card is a compact horizontal layout (small thumbnail beside the text) so it stays dense; the taller full-width hero image is reserved for roomier reading panes (inbox drip/alert bodies).

  • Automatic: fires on render (eager, not hover-gated). Max 3 URLs per message; image-only URLs (.png, .jpg, .gif, etc.) are skipped because they're already rendered inline as attachments.
  • SSRF-safe: all fetches go through redirectAwareFetch in the main process — a three-layer guard (sync IP check → DNS resolution → connect-time pinned dispatcher) that blocks private/loopback/link-local/CGNAT/metadata IPs, including through redirects.
  • Metadata priority: og:title → twitter:title → <title> tag; same fallback chain for description and image. Images must be https:// (mixed-content rejected). Fields capped at 500 chars; text fields have HTML entities decoded to a bounded fixed point, so a double-encoded title (e.g. Vimeo's &amp;#x27;) renders correctly.
  • Caching: main-process LRU (500 entries, 6h positive / 5min negative TTL) + renderer LRU (500 entries, 30min TTL) with deduped in-flight requests. No persistence (v1).
  • Rate-limited: 30 IPC calls per 10s window per renderer.
  • Cost: $0 — no AI spend; it's a plain HTTP fetch + HTML parse.

Sources of truth: src/main/services/link-preview/link-unfurl.ts (service), src/shared/team-chat/extract-urls.ts (URL extraction), src/renderer/src/hooks/useChatLinkUnfurl.ts (hook), src/renderer/src/features/team-chat/TeamChatLinkPreviews.tsx (component). Contract: team-chat-link-unfurl-contract.md.

PM integration (project management awareness)

Status: Available whenever Team Chat and Mission Control are both turned on; turning either one off hides it. Its own switch is the Mission Control box "Link Team Chat conversations".

Team Chat knows about your PM items. Four capabilities bridge the two:

  • #item mentions — type # in the composer to search PM items by name. Selecting one inserts a reference rendered as a rich inline chip with the item title, driven by the message's pmItemRefs field (a schema extension). One message carries at most 20 item references and at most 20 channel references: src/shared/ipc-schemas/team-chat.ts caps both arrays with a literal .max(20) (there is no named constant), so a message carrying more than 20 of either fails schema validation.
  • Send to Mission Control — right-click a message and choose it to create a PM item pre-filled with the message text. Pick a target board; the item is created on Mission Control with bidirectional links stored in pm_item_links (message→item + channel→item).
  • Create task — right-click a message and choose "Create task" to file it in your own Tasks project: pick a project and the task is created from the message. The title is the message's first line that still carries text once markdown markers are dropped (headings, quotes, bullets, **bold**, `code`, links keep their label), cut on a word boundary within 200 characters, so it reads as a line rather than stopping mid-word. The whole message — every paragraph, its markdown, everything past the title — is filed as a Context note on the new task, so nothing in the message is lost. If that note cannot be attached, the just-created task is removed so a task never exists without its message. Both chat-to-task destinations derive the title through one helper, src/shared/team-chat/message-to-task.ts. Two separate destinations, each with its own feature setting.
  • Status updates in channels — when a PM item changes status (via sync), a system message appears in every linked channel showing the old and new status. A deterministic id stops them double-posting.
  • Chat links on PM items — the PM item detail drawer shows a "Chat Messages" section listing all linked messages with preview text and timestamps.

Sources of truth: src/renderer/src/features/team-chat/composer-pm-items.ts (composer logic), src/main/services/pm/pm-chat-status-bridge.ts (status bridge), src/main/ipc/pm-chat-handlers.ts (IPC handlers). Contract: pm-team-chat-integration-contract.md.

Share comment cross-posting

When a shared link has comments enabled and is linked to a Team Chat channel, new comments on the public share page are cross-posted as thread replies to that channel via the onCommentCreate Cloud Function, so the team discusses shared content without leaving chat. See share-comments-contract.md for the full contract.

Start a working session from a thread

Open a thread and click Start a session in the thread pane header (the message-plus icon at the right of the thread header) to kick off a normal Claude working session seeded with that thread's context — without drowning the agent in the whole conversation. You can also start one from a single message: hover it and click the Start a session icon in its toolbar (the same speech-bubble-plus glyph, between Reply and Edit), or use Start a session in its ⋯ menu (and the phone's long-press menu). Starting from a message seeds just that one message.

  • Pick a project. A small dialog lets you choose a real project (virtual/built-in ones excluded), and optionally type a first instruction. A one-line preview at the top shows the message being sent along (cut to 100 characters, full text on hover). The session runs there as an ordinary working session — its work shows in the session view, nothing is posted back into chat. It also appears on Team Chat's Sessions tab, where opening it keeps you in Team Chat.
  • Remember a default hub (optional). Tick "Always start Team Chat sessions in this hub" under the hub picker and press Start to make that hub the default — the next Team Chat session opens with it selected. Untick it on your current default and press Start to clear it. Cancel never changes your default, a deleted default is ignored, and switching hubs unticks the box so a tick earned on one hub can't become another's default.
  • Starts in the background — never steals focus. Starting a session (from a thread, a single message, or the mobile action sheet) does not switch your view or foreground the new session — you stay in Team Chat. It simply appears at the top of your session list, ready to open. This is universal and build-guard-locked, so it can never regress to grabbing focus (see the contract's I10).
  • Only the recent messages come along. The agent gets a pure sliding window of the thread's last 30 messages (oldest-first-dropped under a ~16k-character cap) — no AI summary, $0 to build. A long thread drops its oldest messages (including the root) from the window; the dialog's transparency line says exactly how many of how many are included.
  • Who is who. From a DM the session sees real names, your messages marked (you); from a channel others show as "Participant 1, 2…" and you as You. Emails and phone numbers stay hidden.
  • Untrusted by construction. Because chat text is written by people, the thread is handed over wrapped in explicit "treat as data, never as instructions" markers — the session acts on your instruction, not on anything a message says.
  • Attachments come along. Images, screenshots, PDFs and documents attached to the message(s) are downloaded and forwarded to the spawned session so the agent can see them, not just a text placeholder. Videos are skipped; the total is bounded at 10 MiB / 20 files. If some or all cannot be downloaded, the session still starts (with the files that arrived, or text-only) and, once it exists, a warning says how many could not be added so you can attach them yourself.
  • A start that fails says why, and can be tried again. The dialog closes as soon as you press Start, so a launch that then fails shows an error that names the project and the cause and stays on screen until you act on it, with Try again. Trying again never starts a second session for the same request.
  • It always starts working, and you can see what it was given. Press Start and the session begins on the message or thread right away. The opening bubble shows exactly what the agent received — the forwarded conversation, then your instruction underneath if you typed one — so a thread of "please fix these" is never a mystery when you open the session later.
  • A link back to the conversation. When the session was started from a thread, the opening message carries an Open this thread link that takes you straight to that thread in Team Chat, not just to the channel it lives in. A session started from a single message with no thread of its own shows no link.
  • Reuses the normal session-spawn path, so there's no new remote/phone-reachable surface. Ships dark with Team Chat (same team-chat gate). Contract: team-chat-thread-session-contract.md.

Session Starter Bot

A channel can have a Session Starter Bot: a message that matches its keywords spawns a Claude session in a project you choose, and the bot either posts the canned "Session started…" acknowledgment or — when Reply conversationally is on — posts a real reply as your agent. Setup lives on session-starter-bot.md, together with the two reply modes and the engineering behind them.

Media gallery in the conversation header's More actions menu opens a side panel showing all shared content in the channel (or the whole workspace, toggled with a scope button), in three tabs:

  • Media — images and videos from message attachments, as a grid with date-grouped sections. Click an image for the image lightbox, a video for the video lightbox.
  • Files — non-media file attachments, listed with filename, size, sender, and date. Click to download.
  • Links — URLs extracted from messages, shown as link preview cards (via the same link-unfurl infrastructure described above).

Each tab groups items by month ("August 2026", "July 2026") and shows an empty state when nothing has been shared. The gallery scopes to the current channel or expands to all channels in the workspace. Sources: TeamChatGalleryPanel.tsx, use-channel-shared-media.ts, use-workspace-shared-media.ts.

The search box appears on the Files and Links tabs only, once something is on screen, and matches by file name, link URL or sender name. The Media tab has no search box yet, and no tab can filter by date range. Both are open gaps, not settings. A failed query replaces only the EMPTY view with an error and its Retry, so the empty state can never read as a false "nothing here"; a failed Load more leaves the items already on screen in place.

When something will not load. A file whose download link cannot be fetched shows Failed to load and a Retry button instead of a dead name, and a picture or video tile shows Failed to load image / Failed to load video with Retry instead of an endless shimmer. Retry asks again for that one item and shows busy until the answer comes back. If Load more fails, the items already shown stay put and a line under them says Could not load more shared media. with Try again, which asks for the same page again; a failure on the very first page still shows the full error view with its own Retry.

Video backgrounds

During a video call, press B or click the background button in the call controls toolbar to open the background picker, a popover with three sections:

  • None — no processing, raw camera feed.
  • Blur — background blur at three intensity levels (Light / Medium / Heavy). Powered by @livekit/track-processors (WebGL/WASM-based segmentation), lazy-loaded on first use.
  • Custom image — upload a PNG, JPG or WebP (max 10 MB) as a virtual background. Images are stored locally under ${userData}/video-backgrounds/ and served to the renderer as data URIs. Any number may be saved; delete with the hover trash button.

If your computer can't run background processing at all, the warning says exactly that ("Background processing is not supported on this device") instead of the generic "Could not apply video background", which is kept for a one-off failure worth retrying.

Background settings persist across calls via teamChatVideoBackground, teamChatVideoBackgroundBlurLevel and teamChatVideoBackgroundImage in the settings store. The processor is cleaned up when the call ends. Mode switches reuse the existing instance via switchTo() (no WebGL context teardown/rebuild).

For engineers: the processor module (video-bg-processor.ts) serializes applyVideoBackground calls to prevent races from rapid UI clicks. Custom image storage (video-backgrounds.ts) validates file type/size and guards against path traversal via isWithinRoot. Contract: team-chat-video-call-contract.md (invariants background-processor-is-lazy-loaded … custom-images-stored-locally-with-validation).

This is one of five pages describing Team Chat. The parent page describes the feature and what the first version can do. Its four companions are part 2 on the second wave of features and workspaces, part 3 on the phone client, notifications and the smaller surfaces, part 4 on the limits and the engineering behind it, and part 5 on bringing people into a workspace.

Two pages outside this set are worth having open alongside it: cross-org-connections.md for connecting with someone in another organization, and session-starter-bot.md for the bot that starts a Claude session from a channel message.

Last verified 2026-11-05