Streaming Responses

Relay streams AI responses in real time. As the AI generates text, the Telegram message is progressively edited so you see output as it's produced.

You send a message
The bot sends a "Thinking..." indicator
As text arrives, the message is edited in place with each new chunk
When complete, the final formatted response replaces the streaming preview

A single Telegram message is reused throughout — no new messages are sent until the response is finalized. This avoids notification noise.

Update interval: Every 2 seconds by default (streamEditIntervalMs in ~/.relay/config.json)
Long responses: Automatically split into multiple messages (4096-character Telegram limit)
Tool indicators: Tool use shows human-readable labels with emoji indicators (e.g., "🔧 Read File...", "✅ Read File"). MCP server prefixes are stripped and names are title-cased automatically

File Attachments

When the AI generates files, takes screenshots, or creates artifacts, they are sent as Telegram attachments automatically.

Supported types:

Images (png, jpeg, etc.) — sent as Telegram photos
All other files — sent as documents with the original filename

Voice Messages

Send voice notes to the bot and they'll be transcribed and processed as text input. Add at least one speech-to-text API key to ~/.relay/config.json:

{
  "groqApiKey": "gsk_...",
  "sarvamApiKey": "...",
  "assemblyaiApiKey": "...",
  "openaiSttApiKey": "sk-..."
}

Four STT providers are supported: Groq (fastest, free tier), Sarvam AI (Indian language support), AssemblyAI, and OpenAI. When sttProvider is auto (default), the cheapest configured provider is auto-selected. If it fails, other configured providers are tried automatically. Use /stt to switch providers manually.

Sarvam AI also supports a translate mode (sttProvider: "sarvam-translate") that transcribes non-English voice messages and translates them to English in one step. See Providers for details.

Photo Input

Send photos for analysis by vision-capable models. Add a caption to ask specific questions (e.g., "What's wrong with this UI?"). Without a caption, the AI will describe the image. Check /models for vision badges.

File Input

Send files as attachments. Text files (.txt, .md, .js, .py, .json, .yaml, .toml, .xml, .csv, .html, .css, etc.) are read and embedded directly in the message to the AI. Binary files are referenced by name only. Text files up to 500KB are fully included; larger files are chunked.

Text messages have a 32,000-character limit. For larger content, send as a file attachment.

Built-in MCP Tools

Relay includes 7 built-in MCP (Model Context Protocol) tools that can be enabled during setup or in ~/.relay/config.json. When enabled, Relay auto-configures them in OpenCode.

Browser (Playwright MCP)

Headless browser automation powered by Playwright. The AI can:

Navigate to URLs and take screenshots
Fill forms and click buttons
Extract page content
Execute JavaScript on pages

Enable: "browserEnabled": true

Fetch (Fetch MCP)

Read web pages as clean markdown. The AI can:

Fetch any URL and get readable content
Check API endpoints
Look up documentation

Enable: "fetchEnabled": true

Requires uvx (Python package runner). See Troubleshooting if you encounter issues.

Memory (Memory MCP)

Persistent knowledge graph that survives across sessions. The AI can:

Remember user preferences and decisions
Store project context and patterns
Build up knowledge over time

Enable: "memoryEnabled": true

Data is stored in ~/.relay/memory.jsonl.

Filesystem (Filesystem MCP)

Read and write files outside the current project directory. The AI can:

Access files in specified directories
Work across multiple projects
Read configuration files from other locations

Enable: "filesystemEnabled": true and set "filesystemPaths": ["/path/to/dir"]

GitHub (GitHub MCP)

GitHub API access for issues, PRs, commits, and repository management. The AI can:

List and search issues and pull requests
Read PR diffs and commit history
Create issues and comments

Enable: "githubEnabled": true and set "githubToken": "ghp_..."

Requires a GitHub Personal Access Token (PAT).

Context7 (Documentation MCP)

Version-specific library documentation lookup. The AI can:

Look up latest API docs for any library
Get version-specific documentation
Access up-to-date information beyond training data

Enable: "context7Enabled": true

Optional API key: "context7ApiKey": "..."

Relay (Internal MCP)

Always enabled. Provides AI-driven bot management:

Cron job scheduling (create, update, toggle, run)
Notifications for out-of-band messages
Health checks for system diagnostics

Custom MCP Servers

You can also add custom MCP servers beyond the 7 built-in tools:

Local servers — run as subprocesses:

/mcp add myserver local npx -y @modelcontextprotocol/server-example

Remote servers — connect via URL:

/mcp add api remote https://mcp.example.com/sse

Use /mcp to see all server statuses and /mcp connect <name> to reconnect a server.

Model Selection

Switch between AI models at runtime. /models displays an interactive inline keyboard with capability badges: [reasoning], [vision], [free]. The active model is shown with a ✓ prefix. Tap a button to select a model directly. Pagination buttons appear when there are more than 8 models.

For text-based selection, use /model sonnet, /model deepseek, or a full path like /model anthropic/claude-sonnet-4-20250514.

Models are fetched dynamically from all configured OpenCode providers. If no provider API keys are set, no models are listed.

System Prompt

Customize the AI's behavior with a system prompt file. Place a SKILL.md file in the ~/.relay/ directory and the bot loads it automatically. Change the path in ~/.relay/config.json:

"systemPromptFile": "prompts/my-prompt.md"

The file is watched for changes and reloaded automatically. Force reload with /system reload.

Reasoning / Thinking Display

When using models that support extended thinking (such as those with reasoning capabilities), the AI's reasoning process is displayed separately from the final answer.

Reasoning is shown in a collapsible blockquote (tap to expand) above the answer
If the answer is short enough, reasoning and answer appear in the same message
For longer answers, reasoning is sent as a separate message before the answer chunks
During streaming, reasoning is hidden (shows "Thinking...") until the final answer arrives

Reply Context

Reply to any bot message to reference it in your next prompt. The quoted message text is included as context so the AI knows what you're referring to. Useful for asking follow-up questions about a specific part of a long conversation.

You can also reply to voice notes and audio files — Relay transcribes the audio via STT and includes the transcription as context. Reply context works with all media types: photos, documents, voice, and audio.

Edited Messages

Edit a sent message to re-prompt the AI with the corrected text. The AI processes the edit as a new message with an [Edited message] prefix so it understands this is a correction.

Session Management

Sessions keep conversations organized. Each session maintains its own message history.

Create sessions with /new or /new Refactoring auth module. Fork a session with /fork or /fork msg_abc123. Rename with /rename New title. Use /switch and /delete without arguments for interactive session picker keyboards.

Scheduled Tasks (Cron)

Automate recurring AI tasks that run on a schedule. Define prompts that execute automatically at intervals, daily, weekly, or as a one-time task. All times use your configured timezone (set via /timezone). Results are delivered directly to your Telegram chat.

Creating jobs:

/cron add daily 09:00 Git summary: Summarize recent git commits
/cron add every 30m Health: Check server health
/cron add weekly mon,wed,fri 14:30 Review: Summarize open PRs
/cron add once 14:30 Reminder: Time to review the open PR

The format is always: /cron add <schedule> Title: prompt

Use /cron to see all jobs with action buttons to enable/disable, run now, or delete. The Add Job button walks you through building a schedule step by step via an interactive picker.

Jobs are persisted to cron.json and survive restarts
The scheduler checks for due jobs every 30 seconds
Each job runs in an isolated session (created fresh per run, deleted after) so cron output doesn't pollute your conversation
An animated dots indicator ("Running.", "Running..", "Running...") cycles in the header during execution
A pre-flight health check verifies the AI server is alive before executing
If the bot restarts, missed jobs are skipped (no avalanche of past runs)

Web Monitoring

Monitor any URL for changes and get AI-analyzed notifications when something relevant happens.

Creating a watch:

/watch                                    # Shows list → tap + Add Watch
/watch https://example.com/pricing        # Start with URL pre-filled
/watch add https://example.com/pricing 30 Pricing: Watch for price changes

Both interactive paths lead to a step-by-step flow: URL → interval → task description. The watch name is auto-derived from the URL hostname.

How change detection works:

HTTP fetch — retrieves the page, converts HTML to readable text (strips scripts, styles, tags)
Hash comparison — SHA-256 hash compared against previous snapshot. If identical, done
AI analysis — only when content changes, the AI compares old and new content in an isolated session, filtered by your task description. Irrelevant changes (timestamps, ads, layout) are silently ignored

Upfront validation — when creating a watch, Relay immediately fetches the URL. If the fetch fails, the watch is not created. If the page returns very little content (< 50 words), a warning is shown (possible SPA or bot protection). On success, a baseline snapshot is captured so the first scheduled check can already detect changes.

Use /watch to see all watches with inline buttons to enable/disable, check now, or delete.

Limitations:

JavaScript-rendered pages (SPAs) return only the HTML shell — the upfront validation warns about this
Sites with Cloudflare bot protection will be blocked — caught at creation time
Content is capped at 50KB per snapshot; AI analysis receives up to 3KB

Deep Research

Run thorough multi-step research on any topic:

/research quantum computing advances

The AI creates an isolated session, breaks the topic into 3-5 sub-questions, gathers information from multiple sources, cross-references findings, and delivers a structured report with key findings, analysis, and sources. Results stream live to Telegram. The session is deleted after completion.

Without arguments, /research prompts for the topic interactively.

State Persistence

Relay persists critical state to disk so it survives restarts:

~/.relay/config.json — User configuration
~/.relay/session.json — Current session ID and selected model
~/.relay/cron.json — Scheduled task definitions and run history
~/.relay/watch.json — Web monitoring definitions, snapshots, and check history
~/.relay/SKILL.md — Custom system prompt (optional)
~/.relay/RELAY.md — Auto-generated assembled system prompt (base + MCP docs)
~/.relay/memory.jsonl — Memory MCP knowledge graph data

State is written atomically (temp file + rename) to prevent corruption.

Webhook Deployment

For production, run Relay in webhook mode instead of long-polling.

"botMode": "webhook",
"webhookUrl": "https://your-server.com/bot",
"webhookPort": 39148,
"webhookSecret": "your-random-secret"

Benefits: lower latency, reduced resource usage, better for containerized deployments.