Documentation Index

Fetch the complete documentation index at: https://docs.crewship.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

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

​

1. Open the chat

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

​

2. Send a message

• / to open the slash palette for structured commands (/eval, /checkpoint, /skill <name>).
• Drag, paste, or click-upload an image / file — capped at 25 MB, surfaced to the agent under /output/<agentSlug>/attachments/….
• Pick a different model from the dropdown next to Send for this turn only (handy for switching to Opus mid-conversation for a hard step).

​

3. Watch the agent work

• F1 / Files — live working tree under /workspace.
• F2 / Artifacts — generated reports, screenshots, downloads.
• F3 / Diff — live diff vs. the workspace’s last commit, while the agent is mid-edit.
• F4 / Terminal — read-only tmux attach (OWNER/ADMIN can flip to read-write).

​

4. React or reroll

​

5. Resume later

​

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_PAT" \
  -d '{
    "origin": "WEBHOOK",
    "initial_message": "Triage GH issue #482: Login broken on mobile Safari. Repro steps inside.",
    "metadata": {"github_issue": 482, "repo": "acme/web"}
  }'
# {"chat_id":"cht_xyz789","origin":"WEBHOOK","created_at":"…"}

​

Cross-operator escalation

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

​

API reference

​

Sessions (chats)

​

Messages

​

Reactions

​

Attachments

​

Realtime (WebSocket)

​

Routes

​

Sessions

​

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 stored on the server’s storage provider with a chat_attachments row pointing at them (migration v57). The agent’s container sees the file under /output/<agentSlug>/attachments/<chatId>/<filename>. 25 MB cap per upload.

​

Edit-and-resend

​

Message reactions

​

Right panel

​

Presence and reconnect

​

URL state cheat-sheet

​

Common pitfalls

• Edit-and-resend truncates the active branch — but the tail isn’t gone. Editing a user message moves every message after it into chat_branches. The UI shows a small “view earlier branches” affordance, but a hurried operator may believe they’ve lost the alternate response. Train the muscle of opening the branch picker before assuming work is unrecoverable.
• Reactions are workspace-shared, not per-user-private. A 👎 from one operator is visible to every other operator in the same workspace, and is also surfaced to the agent on the next turn. Use reactions as a deliberate signal — not as a private bookmark. If you need a private flag, use the Inbox pin instead.
• chats.origin silently NULLs unrecognised values. Anything outside the UI / CLI / WEBHOOK / CRON / AGENT allow-list gets stored as NULL to keep the UI chip safe from injection. A webhook handler that posts origin: "github" will succeed (200 OK) but show no chip — the silent failure is by design. Validate the enum on your side before posting.
• Prisma TypeScript schema is intentionally stale on chats.origin. Prisma is types-only in this project; the v59 migration was applied to SQLite but the prisma/schema.prisma was deliberately not regenerated. TS callers must query origin via the Go-typed API surface, not via Prisma Client.
• Attachment cap is 25 MB, with different error surfaces by client. Uploads larger than 25 MB return a 413 from ProxyHandler.AgentChatAttachment. The browser composer surfaces this as a toast, while a programmatic uploader (CLI, webhook) sees only the HTTP error — check status codes before assuming the file landed.
• The Files right-panel shows mid-edit state, not committed state. It reads workspace_files, which tracks the agent’s live working tree. If you want to see what was actually committed by the agent, look at the Diff tab against HEAD, or run git log in the Terminal tab — the Files view is intentionally optimistic.
• Closing the Terminal tab does NOT kill the agent’s tmux session. Re-opening reattaches to the same shell. This is a feature (long-running commands survive a tab close) but operators sometimes assume “close” means “stop”. To actually stop, kill the process inside the terminal first.
• request_id must be stable per logical send, not per React render. Generate the UUID once when the user hits Send, not in the render function. A re-render-derived ID lets the server treat a retry as a new turn — defeating the dedupe contract.
• Slash palette commands must be registered server-side. /foo in the composer where foo isn’t a registered command sends the literal text as a chat message — there’s no client-side “unknown command” error. Add commands via the slash-command registration interface in internal/api/chat.go rather than expecting the UI to discover them.
• Shallow router state evaporates on hard navigation. panel=files survives in-app tab switches and back/forward, but a hard reload that hits a 3xx redirect (e.g. auth expiry → login → bounce) loses everything past ?session=…. Bookmark with intent, not panic.
• WS reconnect dedupes by request_id, not by content. Two genuinely different sends that collide on a re-used request_id will silently merge into one turn server-side. Use a fresh UUID per logical send.
• Right-panel tabs don’t unsubscribe on inactive. Switching from Terminal to Files stops the render of the terminal stream but the WS subscription stays live in the background. This is intentional (re-opening the tab is instant) but means a workspace with many open chat tabs holds many parallel sidecar exec streams — heavy for the sidecar.

​

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 fire on chat.message.created / chat.reaction.added and can drive automation off chat events.
• 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).