​

Chat & Sessions

​

Overview

​

When to use it

• Resume a multi-day conversation. A session ID survives reloads and operator hand-off, so /chat/<agent>?session=<chatId> is the canonical “where we left off” URL. Bookmark it, paste it into Linear, share it on Slack — the recipient lands on the same transcript, the same right-panel state, and (with &panel=files) the same artefact tab.
• Reroll a bad agent response without abandoning context. Hover-edit the user message and the conversation truncates from that point; the new edit sends as a fresh turn. The transcript before the edit is preserved as a chat branch so the alternate timeline isn’t lost — useful when you discover the original direction was right after all.
• Triage what an agent has been doing. The Sessions sidebar groups by chats.origin (UI / CLI / WEBHOOK / CRON / AGENT) so you can see at a glance which conversations were started by the user vs by automation vs by a peer agent. Filter the sidebar to WEBHOOK-origin sessions if you want to audit what an integration has been driving through your agents.
• Watch an agent work in real time without opening the journal. The right-panel Files, Artifacts, Terminal, and Diff tabs stream the live state of the agent’s container while the chat is open. Faster than tailing logs, and the URL deep-links to a specific tab via &panel=files / &panel=terminal.
• Programmatic chat creation from CLI / webhook / cron. POST /api/v1/agents/{agentId}/chats accepts an origin enum on the body and renders a coloured chip in the UI sidebar. Use CLI for crewship run-style invocations, WEBHOOK for trigger-handlers, CRON for scheduled routines, AGENT for peer-to-peer assignments — the chip helps a human operator scrolling the sidebar understand provenance at a glance.

​

Key concepts

​

Usage

https://crewship.example.com/chat/viktor

​

Examples

​

Pair-debugging a failing test

https://crewship.example.com/chat/viktor

​

Webhook-driven issue triage

curl -X POST https://crewship.example.com/api/v1/agents/triage-bot/chats \
  -H "Authorization: Bearer crewship_cli_xxxxx" \
  -d '{"origin": "WEBHOOK"}'
# {"id":"cht_xyz789"}

​

Cross-operator escalation

/chat/viktor?session=cht_abc123&panel=terminal

​

Long conversations & context compaction

[EARLIER CONVERSATION — SUMMARY of older messages no longer shown in full]
…decisions made, facts established, completed work, open threads…
[END EARLIER CONVERSATION]
[CONVERSATION HISTORY - previous messages in this session]
…recent turns, verbatim…

​

Temporally-anchored summaries

​

Robustness at the overflow boundary

• Tool context is never half-shown. When the message that sits on the overflow boundary carries a tool-result summary, it is dropped into the overflow whole (where the summarizer can still capture it) rather than truncated into a half-sentence that references a tool whose result was cut. The one exception is a lone oversized message — it is still truncated so the recent window is never empty.
• Summaries are session-pure. Compaction operates strictly on one session’s history; if a future change ever mixed turns from different sessions into one overflow slice, the orchestrator detects the mismatch and falls back to truncation instead of risking one session’s content leaking into another’s summary.

​

API reference

​

Sessions (chats)

​

Messages

​

Reactions

​

Attachments

​

Participants

​

GET /api/v1/chats//participants

​

POST /api/v1/chats//participants

​

DELETE /api/v1/chats//participants/

• Scoped via chats.workspace_id — a cross-tenant or unknown chat returns 404.
• Mutations (POST / DELETE) require the chat creator or a workspace OWNER/ADMIN; otherwise 403 only the chat owner or a workspace admin can manage participants. A participant whose role is owner is not thereby granted this right — manage-participants permission comes only from being the chat creator or a workspace admin, independent of the per-participant role label.
• Plain members can GET the participant list but cannot mutate it.
• The target user must already be a workspace member, else 400 user is not a member of this workspace.
• Removing the chat owner is rejected with 400 cannot remove the chat owner.

​

Mid-turn steering

​

POST /api/v1/chats//steer

# Redirect a chat — applied on the next turn
crewship chat steer c_abc123 --message "focus on the auth bug first"
crewship chat steer c_abc123 -m "use the staging DB, not prod"

# Scriptable
crewship chat steer c_abc123 -m "tighten the scope" --format json
# → {"queued":true,"in_flight":true}

​

Realtime (WebSocket)

​

Routes

​

Sessions

​

Session names

• whitespace collapses, the text is trimmed, control and invisible formatting characters are dropped (the same normalisation the server applies on write, so the value you see is the value stored);
• it is cut to 60 characters at a word boundary, with an ellipsis only when something was actually cut. A single token longer than that is the one case a word is broken, because the alternative is a base64 paste as the thread’s name;
• a message that is only an attachment is named after the file;
• a message that yields nothing usable — empty, whitespace, ??? — leaves the session untitled. “Untitled session” is a poor name; a thread called … is worse.

• It fires once, on the first message of a session that has no title. Rename a thread yourself and nothing will ever overwrite it — not the next message, not a reload.
• It never blocks the send. The message goes out first and the title follows as a separate request. If that request fails the message is unaffected and nothing is reported; the session simply stays untitled, which is where it already was.
• A rename does not reorder the sidebar. The server does not bump last_activity_at on a rename, and the client splices only the title into the row it already holds — so fixing a name never shoves a thread to the top.

​

Unread badges & last activity

# Which sessions have replies I haven't seen?
crewship chat list atlas
# ID        TITLE            STATUS  MSGS  UNREAD  LAST ACTIVITY     ORIGIN
# c_abc123  Deploy help      ACTIVE  6     2       2026-07-02 09:41  UI

# Read the transcript, then clear the badge + bell item
crewship chat c_abc123
crewship chat read c_abc123            # agent auto-resolved from the chat
crewship chat read c_abc123 --agent atlas   # skip the lookup scan

# Remove an abandoned or one-shot session entirely (irreversible —
# messages and read cursors go with it; creator or agent-editor only)
crewship chat delete c_abc123 --yes

​

“Your agent replied” notifications

• Presence-aware. Watching the reply stream in live means no notification — the bell only rings for replies you’d otherwise miss (closed tab, navigated away, network drop mid-run).
• One item per (user, session). Repeated replies refresh the same unread bell item (timestamp + preview) instead of stacking; a new reply after you dismissed the old item re-notifies.
• Group chats notify every participant except the person whose message triggered the run.
• Previews are scrubbed through the same credential scrubber as logs, so a reply that quotes a token never leaks it into the inbox.
• Opening the session (UI) or crewship chat read clears the item along with the badge.

​

Faithful reload

​

How assistant turns render

• Streamed text reveals at a smooth, constant rate. Network chunks arrive in bursts; the renderer buffers them and reveals characters at a steady pace that speeds up when a backlog builds (e.g. after a reconnect replay), so replies read as a calm flow instead of sentence-sized pops.
• All reasoning of a turn renders as ONE chain-of-thought block. Models interleave thinking ↔ text ↔ tools freely (fast models produce a dozen short passes per reply); every pass merges into a single collapsible block at the position of the first one. While the model reasons, the header shows a live shimmering “Thinking… Ns” timer that accumulates across passes; when the turn finishes it collapses to “Thought for N seconds” (total). Transient progress lines never split the block — a streamed turn renders identically to the same turn reloaded from history.
• Your question pins to the top on send. After you send a message, the conversation anchors your message at the top of the viewport and the reply streams in below it; once the reply outgrows the screen, normal follow-the-stream scrolling (with the scroll-to-bottom pill) resumes.
• Consecutive tool calls collapse into one “Worked · N steps” disclosure with per-tool input/output. A single tool stays a plain card. Interactive tools (AskUserQuestion, TodoWrite, Task) are never grouped.
• Bursts of internal progress / thinking chatter collapse into a single quiet live status line rather than scrolling the transcript.
• Subagent output is indented under its delegation. Text, thinking, and tool calls from a delegation (via the Task tool) are tagged with parent_tool_use_id and rendered indented beneath the delegation in the transcript.

​

Composer

• Slash palette — typing / at the start of a line opens a fuzzy-search palette over registered slash commands (e.g. /eval, /checkpoint, /skill <name>). Commands are registered server-side so a multi-line /eval my-suite --baseline last-week is parsed as a structured command rather than a chat message.
• Model picker — dropdown next to the send button overrides the agent’s default llm_model for this turn only. Useful when an operator wants to spend Opus on a hard reasoning step inside an agent that normally runs Sonnet.
• Attachments — paste images, drag files, or paste image data from the clipboard. Files are uploaded via POST /api/v1/agents/{agentId}/chats/{chatId}/attachments (handler ProxyHandler.AgentChatAttachment in internal/api/proxy_attachments.go) and written to the server’s storage provider as a blob. The agent’s container sees the file under /output/<agentSlug>/attachments/<chatId>/<attachmentId>/<filename>. 25 MB cap per upload. The message names the file. Uploading puts bytes in the container; it does not tell the agent they are there. So when the composer sends a message with attachments, it appends a block naming each one by the path relative to the agent’s working directory (which is /output/<agentSlug>/, so the path the upload returned opens as-is):
  what do you make of this?
  
  I've attached a file to this message. The path is relative to your working directory:
  
  - attachments/cht_xyz789/att_9f2a1c/invoice.pdf
  
  The payload is an ordinary user message — no new envelope, no adapter-specific framing, nothing the agent has to be trained for. The wording is fixed in lib/attachment-message.ts and covered by a table-driven test; the transcript shows the block verbatim, because it is exactly what the agent received. Three consequences worth knowing: a message with no text at all still sends when something is attached (a photo needs no caption); Send is refused while an upload is still in flight, rather than sending a message that names only the files that finished; and the block counts toward the 64 KiB WebSocket frame cap, so a draft that fits on its own can be refused once attachments are added — the draft and the attachments both survive the refusal. The upload also records a row in attachments (owner_type = 'chat') with the filename, resolved content type, size, SHA-256 and uploader — #1768. The blob stays under /output/<agentSlug>/... on purpose: that path is what prompts, tools and users already reference, so chat attachments are not content-addressed the way issue attachments are, and storage_key on the row is what says where each one lives. What the path gained is an <attachmentId> segment before the filename, which makes one upload one identity at one location — two different files called evidence.pdf no longer overwrite each other. Listing and deletion live at GET/DELETE /api/v1/agents/{agentId}/chats/{chatId}/attachments[/{attachmentId}]; there is still no download endpoint.

​

Edit-and-resend

​

Message reactions

​

Right panel

​

Presence and reconnect

​

URL state cheat-sheet

​

Common pitfalls

​

Group chats (multiple humans + the agent)

crewship chat participants add <chat-id> <user-id>                # add (promotes to group)
crewship chat participants add <chat-id> <user-id> --role owner   # add as an owner
crewship chat participants list <chat-id>                         # who's in the chat
crewship chat participants remove <chat-id> <user-id>             # remove

• The agent runs under the chat’s own credentials, the same for every participant — there’s no per-user data grounding yet. Don’t share a group chat with people who shouldn’t see what the agent can reach.
• Mention matching is by slug on a word boundary (case-insensitive), so email@riley.com and @rileybot do not mention agent riley.
• @mention autocomplete is available in the composer (wired in PR #702), so you can pick the agent from a dropdown instead of typing the slug by hand. Only presence / typing indicators remain unshipped; live message sync works today.
• Adding a participant does not introduce per-message visibility controls — anyone who can see the chat sees the whole transcript.

​

Related

• Activity — the live canvas where the same agent’s mission runs show up; the chat is one operator surface, Activity is the other.
• Watch Roster — the source of truth for the composer presence chip (online / thinking / blocked / offline).
• Quartermaster — replays consume message reactions as a coarse human-feedback signal (👍 / 👎 surfaces back to evals).
• Skills — slash-palette commands like /skill <name> route into the skills registry rather than being treated as chat messages.
• Hooks — server-side handlers that can drive automation off agent lifecycle events. (Note: there are no chat.message.* / chat.reaction.* events today — see Realtime above.)
• Files and output — the workspace_files blob index that the Files right-panel reads from; same view the agent’s container sees.
• Keeper — credential injection for tools the agent invokes from inside a chat; keeps secrets out of message bodies.
• User preferences API — composer settings (default model, slash-palette behaviour).
• Conversations API — message reactions, attachments, crew messaging.
• Webhooks — programmatic chat-session creation (origin=WEBHOOK).