@4via6/relay 1.0.0

package/docs/commands.md

@@ -0,0 +1,351 @@
+# Command Reference
+
+Complete reference for all Relay Telegram commands. Commands marked with a provider name are only available when using that provider.
+
+## Chat
+
+No command needed -- just send a message.
+
+**Supported input types:**
+- Text messages
+- Voice notes (requires STT configuration)
+- Photos (sent to vision-capable models)
+- File attachments (text files are embedded, binary files referenced)
+
+**Input limit:** 32,000 characters for text messages. Send longer content as a file.
+
+**Output:** The AI's response is sent as Telegram messages. If the AI generates files or screenshots (OpenCode), they are sent as Telegram attachments automatically.
+
+---
+
+## Session Management
+
+### `/new [title]`
+
+Create a new session.
+
+```
+/new
+/new Refactoring auth module
+```
+
+The new session becomes the active session. All subsequent messages go to this session.
+
+### `/sessions`
+
+List all sessions, sorted by last modified date. Shows the session ID, title, and a marker for the active session.
+
+### `/switch <id>`
+
+Switch to an existing session by its ID.
+
+```
+/switch abc123
+```
+
+### `/delete <id>`
+
+Delete a session. If you delete the active session, it is cleared.
+
+```
+/delete abc123
+```
+
+### `/current`
+
+Show the currently active session's ID and title.
+
+### `/fork [messageId]`
+
+Fork the current session, creating a copy. Optionally specify a message ID to fork from a specific point.
+
+```
+/fork
+/fork msg_abc123
+```
+
+The forked session becomes the active session. Supported by OpenCode and Claude.
+
+---
+
+## Monitor
+
+### `/todo` (OpenCode)
+
+View the AI's task checklist. Shows each task with a status icon:
+
+- Completed
+- In progress
+- Pending
+- Cancelled
+
+### `/diff`
+
+Show a summary of code changes in the current session. OpenCode shows structured file-level changes; Claude and Codex delegate to `git diff`.
+
+### `/diff full`
+
+Download the full diff as a text file, including before/after content for each changed file.
+
+---
+
+## File Operations
+
+### `/read <path>`
+
+Read a file and display its contents.
+
+```
+/read src/index.ts
+/read package.json
+```
+
+Files larger than 15KB are sent as a downloadable attachment.
+
+### `/find <query>`
+
+Find files by name pattern.
+
+```
+/find index.ts
+/find *.json
+```
+
+Shows up to 50 matching files.
+
+### `/search <pattern>`
+
+Search file contents with a text pattern (regex supported).
+
+```
+/search TODO
+/search function.*auth
+```
+
+Shows up to 20 matching lines with file paths and line numbers.
+
+### `/symbols <query>`
+
+Find code symbols (functions, classes, variables) by name.
+
+```
+/symbols authenticate
+/symbols UserService
+```
+
+Shows up to 30 matching symbols with their locations.
+
+### `/status`
+
+Show git file status (modified, added, deleted files).
+
+---
+
+## History
+
+### `/history`
+
+View the last 10 messages in the current session. Shows alternating user and assistant messages with a 200-character preview.
+
+### `/summarize`
+
+Generate a summary of the current session. OpenCode only.
+
+### `/revert`
+
+Undo the last AI change. OpenCode only.
+
+### `/unrevert`
+
+Redo a previously reverted change. OpenCode only.
+
+### `/abort`
+
+Cancel the currently running operation. Stops streaming or processing.
+
+### `/share`
+
+Get a shareable URL for the current session. OpenCode only.
+
+---
+
+## Shell
+
+### `/shell <command>`
+
+Run a shell command on the coding agent's machine.
+
+```
+/shell ls -la
+/shell git log --oneline -5
+/shell npm test
+```
+
+On OpenCode, this runs natively. On Claude and Codex, the command is sent as a prompt asking the AI to execute it.
+
+### `/cmd <command> [arguments]` (OpenCode)
+
+Run an OpenCode-specific command.
+
+```
+/cmd compact
+/cmd agent_cycle
+```
+
+### `/commands` (OpenCode)
+
+List all available OpenCode commands that can be used with `/cmd`.
+
+---
+
+## Models
+
+### `/models`
+
+List all available models grouped by provider. Each model shows capability badges:
+
+- `[reasoning]` -- The model supports extended thinking/reasoning
+- `[vision]` -- The model accepts image input
+- `[active]` -- Currently selected model
+
+Example output:
+
+```
+Available Models
+
+anthropic
+  claude-sonnet-4-20250514  [reasoning] [active]
+  claude-opus-4-20250514  [reasoning]
+  claude-haiku-4-20250514
+
+openrouter
+  deepseek/deepseek-r1  [reasoning]
+```
+
+All providers fetch models dynamically from their respective APIs.
+
+### `/model [provider/model]`
+
+View or change the current model.
+
+**View current model:**
+```
+/model
+```
+
+**Set by full path:**
+```
+/model anthropic/claude-sonnet-4-20250514
+```
+
+**Set by partial match:**
+```
+/model sonnet
+/model deepseek
+```
+
+After switching, the bot shows the model's capabilities:
+
+```
+Model set to anthropic/claude-sonnet-4-20250514
+Capabilities: reasoning, vision
+```
+
+---
+
+## MCP (Model Context Protocol)
+
+MCP servers extend the AI's capabilities with additional tools like browsers, databases, and external APIs. Supported by OpenCode and Claude.
+
+### `/mcp`
+
+Show the status of all configured MCP servers.
+
+Example output:
+
+```
+MCP Servers (2)
+
+memory  ok
+browser  failed
+  Connection refused
+```
+
+### `/mcp add <name> local <command...>`
+
+Add a local MCP server. The command is run as a subprocess.
+
+```
+/mcp add memory local npx -y @modelcontextprotocol/server-memory
+/mcp add browser local npx -y @anthropic-ai/mcp-server-puppeteer
+/mcp add filesystem local npx -y @modelcontextprotocol/server-filesystem /path/to/dir
+```
+
+### `/mcp add <name> remote <url>`
+
+Add a remote MCP server by URL.
+
+```
+/mcp add api remote https://mcp.example.com/sse
+```
+
+### `/mcp remove <name>`
+
+Remove and disconnect an MCP server.
+
+```
+/mcp remove browser
+```
+
+**Provider differences:**
+- **OpenCode:** Full runtime management. Servers persist in the OpenCode configuration.
+- **Claude:** Persisted to `.relay/claude-mcp.json`. Servers are restored on restart.
+- **Codex:** Not supported.
+
+---
+
+## Settings
+
+### `/health`
+
+Show a dashboard with server status, current model (with reasoning badge), streaming status, voice STT provider, system prompt info, and project details.
+
+### `/config`
+
+Show the full provider configuration as JSON.
+
+### `/providers`
+
+Show available AI providers and their models (raw JSON from the provider).
+
+### `/agents`
+
+List available agents (OpenCode only).
+
+### `/tools`
+
+List all tools available to the AI.
+
+### `/project`
+
+Show project information: ID, worktree, VCS type, branch, and directory.
+
+### `/git`
+
+Show git branch and changed files status.
+
+### `/system`
+
+View the current system prompt (first 500 characters), its source (custom file or built-in default), and character count.
+
+### `/system reload`
+
+Force-reload the system prompt from the file. Useful if auto-reload didn't pick up a change.
+
+### `/start`
+
+Show a welcome message with the active provider name.
+
+### `/help`
+
+Show a compact reference of all available commands, with provider-specific sections shown based on the active provider.

package/docs/configuration.md

@@ -0,0 +1,160 @@
+# Configuration Reference
+
+All configuration is done through environment variables in the `.env` file. Copy `.env.example` to `.env` to get started.
+
+## Required Variables
+
+| Variable | Description |
+|----------|-------------|
+| `BOT_TOKEN` | Telegram bot token from [@BotFather](https://t.me/BotFather) |
+| `ALLOWED_USER_ID` | Your Telegram user ID (only this user can interact with the bot) |
+| `PROVIDER` | Which coding agent to use: `opencode`, `claude`, or `codex` |
+
+## Provider Configuration
+
+Each provider has its own set of required and optional variables. See [Providers](providers.md) for detailed setup.
+
+### OpenCode
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENCODE_MODE` | No | `start` | `start` spawns a local server, `connect` connects to a remote URL |
+| `OPENCODE_URL` | No | `http://localhost:4096` | Server URL (used when `MODE=connect`) |
+| `OPENCODE_HOSTNAME` | No | `127.0.0.1` | Bind address (used when `MODE=start`) |
+| `OPENCODE_PORT` | No | `4096` | Port number (used when `MODE=start`) |
+| `OPENCODE_MODEL` | No | Server default | Model override, e.g. `anthropic/claude-sonnet-4-20250514` |
+
+### Claude Code
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `ANTHROPIC_API_KEY` | Yes | -- | Anthropic API key |
+| `CLAUDE_MODEL` | No | `sonnet` | Model name or ID (use `/models` to see all available) |
+| `CLAUDE_PERMISSION_MODE` | No | `acceptEdits` | How Claude handles file edits |
+| `CLAUDE_CWD` | No | Current directory | Working directory for Claude |
+
+### OpenAI Codex
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CODEX_API_KEY` | Yes* | -- | OpenAI API key (*or use `OPENAI_API_KEY`) |
+| `CODEX_MODEL` | No | `o3` | Model name or ID (use `/models` to see all available) |
+| `CODEX_CWD` | No | Current directory | Working directory for Codex |
+
+## Bot Mode
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BOT_MODE` | `polling` | `polling` for long-polling, `webhook` for webhook mode |
+| `WEBHOOK_URL` | -- | Public URL for receiving Telegram updates (required when `BOT_MODE=webhook`) |
+| `WEBHOOK_PORT` | `3000` | Port for the webhook HTTP server |
+| `WEBHOOK_SECRET` | -- | Optional secret token for webhook verification |
+
+### Long Polling (default)
+
+The bot connects to Telegram and pulls updates. Simple to set up, works behind NATs/firewalls.
+
+```env
+BOT_MODE=polling
+```
+
+### Webhook Mode
+
+The bot runs an HTTP server and Telegram pushes updates to it. Lower latency and better for production deployments.
+
+```env
+BOT_MODE=webhook
+WEBHOOK_URL=https://your-server.com/bot
+WEBHOOK_PORT=3000
+WEBHOOK_SECRET=your-random-secret
+```
+
+Requirements:
+- A public HTTPS URL that Telegram can reach
+- The port must be accessible (default: 3000)
+
+## Data Persistence
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `RELAY_DATA_DIR` | `.relay/` | Directory for persisted bot state |
+
+Relay persists session state, model selection, and provider-specific data to disk so they survive restarts. The `.relay/` directory is created automatically in the project root.
+
+Files stored:
+- `session.json` — Active session ID and selected model
+- `claude-mcp.json` — Claude provider MCP server configurations
+- `codex-threads.json` — Codex provider thread ID mappings
+
+The directory is excluded from git via `.gitignore`.
+
+## Streaming
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STREAMING_ENABLED` | `false` | Enable progressive message editing during AI responses |
+| `STREAM_EDIT_INTERVAL_MS` | `2000` | How often (in ms) to update the Telegram message while streaming |
+
+When streaming is enabled, the bot sends a "Thinking..." placeholder and progressively updates it as the AI generates its response. This works with all three providers.
+
+## Timeout
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PROMPT_TIMEOUT_MS` | `300000` | Maximum time (in ms) to wait for a provider response. Default is 5 minutes. |
+
+If the AI takes longer than this to respond, the request is cancelled and an error message is shown.
+
+## System Prompt
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SYSTEM_PROMPT_FILE` | `skill.md` | Path to your custom system prompt file |
+
+The bot looks for a file named `skill.md` in the project root. If found, its contents are prepended to every message sent to the AI. If the file doesn't exist, a built-in default prompt is used.
+
+The file is watched for changes and reloaded automatically. You can also force a reload with `/system reload`.
+
+See [Features > System Prompt](features.md#system-prompt) for details on customizing the prompt.
+
+## Voice / Speech-to-Text
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `STT_PROVIDER` | `auto` | STT provider: `groq`, `openai`, `assemblyai`, or `auto` |
+| `GROQ_API_KEY` | -- | Groq API key for Whisper |
+| `GROQ_STT_MODEL` | `whisper-large-v3-turbo` | Groq transcription model |
+| `OPENAI_API_KEY` | -- | OpenAI API key for Whisper |
+| `OPENAI_STT_MODEL` | `gpt-4o-mini-transcribe` | OpenAI transcription model |
+| `ASSEMBLYAI_API_KEY` | -- | AssemblyAI API key |
+
+Set at least one API key to enable voice message support. When `STT_PROVIDER=auto` (default), the cheapest available provider is selected automatically:
+
+1. **Groq** (fastest, has a free tier)
+2. **AssemblyAI**
+3. **OpenAI**
+
+## Example `.env` File
+
+```env
+# Telegram
+BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
+ALLOWED_USER_ID=987654321
+
+# Provider
+PROVIDER=opencode
+OPENCODE_MODE=start
+
+# Bot mode (polling or webhook)
+BOT_MODE=polling
+
+# Streaming
+STREAMING_ENABLED=true
+STREAM_EDIT_INTERVAL_MS=2000
+
+# Timeout
+PROMPT_TIMEOUT_MS=300000
+
+# Voice (set at least one for voice support)
+GROQ_API_KEY=gsk_...
+```