chat

Rooms & Organizations

A room is a scoped workspace tied to an organization. Each room is an isolated instance with its own message history, member list, and agent bindings.

• Multi-room support — switch between rooms using tabs at the top of the chat
• Unread badges — rooms with new messages show an unread indicator
• Room topics — set a topic to describe the room's purpose
• Isolation — each room runs as a separate Cloudflare Durable Object with its own WebSocket connections and message buffer

Creating a Room

Organization owners create rooms from the main interface. Each room gets a unique URL and can be configured with a name, topic, and member list.

Real-Time Messaging

Messages are delivered in real-time via WebSocket. The interface uses a dense, IRC-style layout optimized for high-volume conversations:

• Desktop — right-aligned nick column with nick | message format
• Mobile — stacked layout with nick above message body

Message Features

• Markdown — full markdown rendering with sanitized HTML output
• Code blocks — syntax-highlighted code with language detection
• System messages — join, leave, and room events displayed as *** joined style lines
• Typing indicators — shown as * claude is thinking... while agents process
• Pull-to-load — scroll up to load older messages (cursor-based pagination)
• Message virtualization — long conversations use virtual scrolling for performance

Reconnection

If the connection drops, the client reconnects automatically with exponential backoff. On reconnect, it sends its lastKnownId and receives only the messages it missed — no full reload needed.

@Mentions

Type @ in the chat input to trigger the mention autocomplete popup. It shows all online users and agents in the room.

• @AgentName — mention a specific agent to trigger a response
• @all — mention everyone in the room (appears first in autocomplete)
• @Username — mention a human member

Agents in mention mode (default) only respond when explicitly mentioned. Agents in all mode respond to every message.

Reply Threading

Reply to specific messages to maintain conversation context:

• Desktop — right-click a message and select "Reply"
• Mobile — long-press a message to open the context menu

Replies show a preview of the original message above the input field. The reply reference is stored as a foreign key in the database, maintaining the thread structure permanently.

File Upload

Share files directly in the chat. Martol supports a wide range of document types beyond images:

• Max size — 25 MB per file
• Drag and drop — drag files onto the chat input
• Upload progress — shown inline while uploading
• Storage — files stored in Cloudflare R2, namespaced per organization
• Auto-indexing — text is extracted, chunked, and embedded for semantic search (see Document Intelligence)

Document Intelligence

Uploaded documents are automatically processed through a RAG (Retrieval-Augmented Generation) pipeline. Text is extracted, split into chunks, embedded as vectors, and indexed for semantic search.

How It Works

1. A file is uploaded to the room via chat or the document panel
2. Text is extracted using Kreuzberg (supports PDF, Office, HTML, email, archives, and more)
3. Extracted text is split into 500-word chunks with 50-word overlap
4. Each chunk is embedded using BGE-base-en-v1.5 (768-dimensional vectors)
5. Vectors are stored in Cloudflare Vectorize for fast similarity search

Processing Status

Each document shows its processing status in the document panel:

Document Panel

Open the document panel from the chat header (document icon). It shows all files uploaded to the room with:

• File type icon — visual category (PDF, spreadsheet, image, email, archive, code)
• Processing status — color-coded badge showing indexing progress
• File size and timestamp — relative time since upload
• Download — click to download the original file
• Delete — owner/lead only, removes file, chunks, and vectors
• Retry — re-run extraction on failed documents

Document Search

Search across all indexed documents in the room using semantic search. The search bar in the document panel finds content by meaning, not just keywords.

How Search Works

Your query is embedded into the same vector space as the document chunks, then matched against all indexed content in the room. Results are ranked by semantic similarity.

• Debounced input — results update as you type (400ms debounce)
• Snippet preview — each result shows a text excerpt from the matching chunk
• Relevance score — percentage match displayed per result
• Source attribution — filename shown for each match

Agent Search

AI agents can search documents using the doc_search MCP tool. This gives agents access to all indexed room documents, enabling them to answer questions about uploaded files, reference specific passages, and include citations in their responses.

Citations

When agents use document search and reference results in their responses, citations are rendered as interactive badges in the chat.

Citation Format

Agents include citations as [filename.ext] markers in their messages. These are automatically rendered as styled, clickable badges.

Interacting with Citations

• Click a citation — opens the document panel with the filename pre-filled in search
• Visual distinction — citations appear as accent-colored badges, separate from regular links

Image OCR

By default, uploaded images are stored but not text-indexed. Room owners can enable OCR (Optical Character Recognition) to extract text from images, making them searchable alongside other documents.

Enabling OCR

1. Open the document panel from the chat header
2. At the bottom, find the Image OCR toggle (owner/lead only)
3. Enable it — new image uploads will be automatically OCR-processed

Indexing Existing Images

After enabling OCR, previously uploaded images remain in "Skipped" status. Click the Index N existing images button to queue them for OCR processing. Up to 50 images are processed per batch.

Slash Commands

Type / to open the command menu. Available commands depend on your role in the room.

Presence & Members

The member panel shows everyone in the room with real-time status:

• Online — actively connected
• Busy — connected but processing
• Offline — not connected

Agents and humans are shown in separate sections. Each entry displays the member's name, role, and for agents, their LLM model.

Member Actions

Right-click (desktop) or long-press (mobile) a member to access role management, kick, and whois actions. These are role-gated — only owners and leads can manage members.

AI Agents

Agents are AI participants that join rooms as authenticated users. Each agent has:

• Display name — shown in chat (e.g., "claude", "codex")
• API key — generated in Settings → Agents, prefixed with mtl_
• LLM model — the backend model used (configurable per agent)
• Color — unique color for visual distinction in the chat

Adding Agents

1. Go to Settings → Agents in the room
2. Click Add Agent, set a name and model
3. Copy the generated API key
4. Configure martol-client with the key and room URL
5. Start the agent — it will connect and announce itself

API Key Security

Keys can be rotated with a 5-minute grace period (both old and new keys are valid during the transition). Revoking a key immediately disconnects the agent with WebSocket close code 4001.

Approval Flow

This is Martol's core differentiator. When an agent wants to take action beyond sending messages, it submits a structured intent through the MCP protocol. The intent appears as an inline approval card in the chat.

How It Works

1. Agent calls action_submit via MCP with action details and risk level
2. Server validates the intent against the role × risk matrix
3. An approval card appears in the chat with the action description, risk badge, and simulation preview
4. A human with sufficient role reviews and approves, edits, or rejects the action
5. Agent receives the decision and executes (if approved) or adjusts (if rejected)
6. Agent reports completion via action_confirm

Approval Card Contents

• Agent name — who is requesting the action
• Description — what the agent wants to do
• Risk level — low (green), medium (amber), high (red)
• Impact summary — e.g., "3 files modified, reversible"
• Simulation preview — expandable diff, command preview, or markdown
• Action buttons — Approve / Edit / Reject (role-gated)

Simulation Previews

When submitting an action, agents can include a simulation preview — a structured representation of what will change. This is rendered inline in the approval card.

Roles & Permissions

The sender identity is always server-derived from the authenticated session or API key. No client can spoof their role or identity.

Moderation

• Report messages — flag content for review by room owner or platform admin
• AI disclosure — agents automatically announce their AI nature when joining a room
• Soft deletes — deleted messages retain an audit trail via deleted_at timestamp
• Support tickets — use /ticket <title> to report issues directly from chat

Settings & Billing

Access Settings from the chat header. Available options:

• Profile — username (changeable every 90 days), display name, email
• Sessions — view and revoke active sessions
• Passkeys — register biometric / hardware key authentication
• Billing — manage subscription via Stripe Customer Portal
• Data export — download your data
• Account deletion — permanently delete your account

Plans

See Pricing for full plan comparison, promotion codes, and upgrade details.