@4via6/relay 1.0.0

package/docs/providers.md

@@ -0,0 +1,236 @@
+# Provider Setup
+
+Relay supports three coding agent backends. Each provider connects the bot to a different AI coding tool. Set `PROVIDER` in your `.env` file to choose one.
+
+## OpenCode
+
+[OpenCode](https://github.com/opencode-ai/opencode) is the recommended provider with the most complete feature set. It supports all Relay features including file operations, todos, diffs, MCP management, and dynamic model listing.
+
+### Installation
+
+The OpenCode SDK is included as a core dependency -- no extra installation needed.
+
+### Configuration
+
+There are two modes of operation:
+
+#### Mode 1: Start (recommended)
+
+Relay spawns and manages the OpenCode server automatically.
+
+```env
+PROVIDER=opencode
+OPENCODE_MODE=start
+OPENCODE_HOSTNAME=127.0.0.1
+OPENCODE_PORT=4096
+```
+
+#### Mode 2: Connect
+
+Connect to an already-running OpenCode server. Use this when the server is running on a different machine or managed separately.
+
+```env
+PROVIDER=opencode
+OPENCODE_MODE=connect
+OPENCODE_URL=http://localhost:4096
+```
+
+If you connect to a remote server over HTTP, the bot will show a warning. Use HTTPS for production deployments.
+
+### Model Selection
+
+OpenCode supports many AI providers and models. Set a default model:
+
+```env
+OPENCODE_MODEL=anthropic/claude-sonnet-4-20250514
+```
+
+Or change models at runtime:
+
+```
+/models              -- List all configured models
+/model anthropic/claude-sonnet-4-20250514  -- Switch to a specific model
+/model sonnet        -- Partial match
+```
+
+### OpenCode Configuration
+
+OpenCode itself is configured through its own config file (typically `opencode.json` or via environment variables). Refer to the [OpenCode documentation](https://opencode.ai/docs) for:
+
+- Adding AI providers (Anthropic, OpenAI, Google, etc.)
+- Configuring MCP servers in the config file
+- Setting up agent modes (build, plan, explore)
+- Tool permissions and security settings
+
+### Supported Features
+
+All Relay features are supported:
+- Sessions, streaming, file operations
+- Todo lists, diffs, session forking
+- Shell access, custom commands
+- MCP server management
+- Dynamic model listing with capabilities
+- Outbound file attachments (screenshots, generated files)
+
+---
+
+## Claude Code
+
+[Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview) connects to the Anthropic Claude AI with full coding agent capabilities.
+
+### Installation
+
+Install the Claude Code SDK:
+
+```bash
+npm install @anthropic-ai/claude-code
+```
+
+### Configuration
+
+```env
+PROVIDER=claude
+ANTHROPIC_API_KEY=sk-ant-api03-...
+CLAUDE_MODEL=sonnet
+CLAUDE_PERMISSION_MODE=acceptEdits
+CLAUDE_CWD=/path/to/your/project
+```
+
+### API Key
+
+Get your API key from the [Anthropic Console](https://console.anthropic.com/). The key must have access to the Claude Code API.
+
+### Models
+
+Models are fetched dynamically from the Anthropic API (`GET /v1/models`), so new models are automatically available without a bot update.
+
+Use `/models` to see all available models, and `/model <id>` to switch:
+
+```
+/models              -- List all available Anthropic models
+/model sonnet        -- Switch by alias
+/model claude-opus-4-0-20250514  -- Switch by full ID
+```
+
+### Permission Mode
+
+The `CLAUDE_PERMISSION_MODE` controls how Claude handles file system operations:
+
+- `acceptEdits` -- Automatically accept file edits (recommended for bot use)
+- Other modes may require interactive approval, which won't work in a bot context
+
+### Working Directory
+
+Set `CLAUDE_CWD` to the project directory you want Claude to work in. Defaults to the directory where Relay is running.
+
+### MCP Servers
+
+Claude supports MCP servers configured at runtime through the bot:
+
+```
+/mcp add memory local npx -y @modelcontextprotocol/server-memory
+/mcp add browser local npx -y @anthropic-ai/mcp-server-puppeteer
+```
+
+MCP configs are persisted to `.relay/claude-mcp.json` and automatically restored on restart.
+
+### Supported Features
+
+| Feature | Status |
+|---------|--------|
+| Chat, streaming | Supported |
+| Sessions | Create, list, delete, fork |
+| Shell access | Via prompt (asks Claude to run commands) |
+| MCP management | Persisted to disk |
+| Model selection | Dynamic (fetched from Anthropic API) |
+| File operations | Via prompt delegation (read, find, search, git status) |
+| Code diffs | Via prompt delegation (git diff) |
+| History | Supported (session message history) |
+| Todos | Not supported |
+| Session sharing | Not supported |
+
+---
+
+## OpenAI Codex
+
+[OpenAI Codex](https://github.com/openai/codex) provides coding agent capabilities using OpenAI's reasoning models.
+
+### Installation
+
+Install the Codex SDK:
+
+```bash
+npm install @openai/codex
+```
+
+### Configuration
+
+```env
+PROVIDER=codex
+CODEX_API_KEY=sk-...
+CODEX_MODEL=o3
+CODEX_CWD=/path/to/your/project
+```
+
+You can use either `CODEX_API_KEY` or `OPENAI_API_KEY`. If both are set, `CODEX_API_KEY` takes priority.
+
+### Models
+
+Models are fetched dynamically from the OpenAI API (`GET /v1/models`), so new models are automatically available without a bot update.
+
+Use `/models` to see all available models, and `/model <id>` to switch:
+
+```
+/models              -- List all available OpenAI models
+/model o3            -- Switch to o3
+/model o4-mini       -- Switch to o4-mini
+```
+
+### Working Directory
+
+Set `CODEX_CWD` to the project directory. Defaults to the directory where Relay is running.
+
+### Supported Features
+
+| Feature | Status |
+|---------|--------|
+| Chat, streaming | Supported |
+| Sessions | Create, list, delete (persisted to disk) |
+| Shell access | Via prompt (asks Codex to run commands) |
+| MCP management | Not supported |
+| Model selection | Dynamic (fetched from OpenAI API) |
+| File operations | Via prompt delegation (read, find, search, git status) |
+| Code diffs | Via prompt delegation (git diff) |
+| Todos | Not supported |
+| Session sharing | Not supported |
+
+---
+
+## Provider Comparison
+
+| Feature | OpenCode | Claude | Codex |
+|---------|----------|--------|-------|
+| Streaming | yes | yes | yes |
+| File output (screenshots) | yes | no | no |
+| MCP management | full API | persisted | no |
+| Model listing | dynamic | dynamic (API) | dynamic (API) |
+| Todo tracking | yes | no | no |
+| Code diffs | yes | via prompt | via prompt |
+| Session forking | yes | yes | no |
+| Revert changes | yes | no | no |
+| File operations | yes | via prompt | via prompt |
+| History | yes | yes | no |
+| Shell commands | native | via prompt | via prompt |
+| Custom commands | yes | no | no |
+| Session sharing | yes | no | no |
+| State persistence | via config | yes | yes |
+
+## Switching Providers
+
+To switch providers, update the `PROVIDER` variable in `.env` and restart the bot:
+
+```env
+PROVIDER=claude  # or opencode, codex
+```
+
+Sessions are provider-specific and not shared between providers. Switching providers starts fresh.

package/docs/troubleshooting.md

@@ -0,0 +1,287 @@
+# Troubleshooting
+
+Common issues and solutions when running Relay.
+
+---
+
+## Bot won't start
+
+### "BOT_TOKEN is required"
+
+You haven't set the Telegram bot token. Add it to your `.env` file:
+
+```env
+BOT_TOKEN=123456:ABC-DEF...
+```
+
+Get a token from [@BotFather](https://t.me/BotFather) on Telegram.
+
+### "Unknown provider: xyz"
+
+The `PROVIDER` value in `.env` is not one of `opencode`, `claude`, or `codex`. Check for typos:
+
+```env
+PROVIDER=opencode
+```
+
+### "Cannot find package '@anthropic-ai/claude-code'"
+
+The Claude Code SDK is not installed. Install it:
+
+```bash
+npm install @anthropic-ai/claude-code
+```
+
+### "Cannot find package '@openai/codex'"
+
+The Codex SDK is not installed. Install it:
+
+```bash
+npm install @openai/codex
+```
+
+---
+
+## Authentication
+
+### Bot doesn't respond to messages
+
+Relay only responds to authorized users. Check your `ALLOWED_USER_ID`:
+
+```env
+ALLOWED_USER_ID=123456789
+```
+
+To find your Telegram user ID, send a message to [@userinfobot](https://t.me/userinfobot).
+
+### Multiple users
+
+Separate multiple user IDs with commas:
+
+```env
+ALLOWED_USER_ID=123456789,987654321
+```
+
+---
+
+## OpenCode Issues
+
+### "Connection refused" when using connect mode
+
+The OpenCode server isn't running or isn't reachable at the configured URL:
+
+1. Check that the OpenCode server is running
+2. Verify the URL in your `.env`:
+   ```env
+   OPENCODE_URL=http://localhost:4096
+   ```
+3. If the server is on a different machine, ensure the port is open and the host is correct
+
+### "Failed to start OpenCode server" in start mode
+
+Relay couldn't spawn the OpenCode server. Check:
+
+1. OpenCode is installed and in your PATH
+2. The port isn't already in use:
+   ```bash
+   lsof -i :4096
+   ```
+3. Check the configured host and port:
+   ```env
+   OPENCODE_HOSTNAME=127.0.0.1
+   OPENCODE_PORT=4096
+   ```
+
+### HTTP warning for remote OpenCode
+
+If you see a warning about connecting over HTTP, it means your `OPENCODE_URL` uses `http://` instead of `https://`. This is fine for local development but use HTTPS for production:
+
+```env
+OPENCODE_URL=https://your-server.example.com:4096
+```
+
+---
+
+## Claude Code Issues
+
+### "Invalid API key"
+
+Your Anthropic API key is invalid or expired:
+
+1. Check the key in `.env`:
+   ```env
+   ANTHROPIC_API_KEY=sk-ant-api03-...
+   ```
+2. Verify the key at [console.anthropic.com](https://console.anthropic.com/)
+3. Ensure the key has Claude Code API access
+
+### Claude doesn't modify files
+
+Claude Code requires the `acceptEdits` permission mode to automatically accept file operations in a bot context:
+
+```env
+CLAUDE_PERMISSION_MODE=acceptEdits
+```
+
+Without this, Claude may prompt for interactive approval, which doesn't work in a Telegram bot.
+
+### Wrong working directory
+
+Claude operates in the directory specified by `CLAUDE_CWD`. If files aren't found, check the path:
+
+```env
+CLAUDE_CWD=/path/to/your/project
+```
+
+Defaults to the directory where Relay is running.
+
+---
+
+## Codex Issues
+
+### "Invalid API key"
+
+Check your OpenAI API key:
+
+```env
+CODEX_API_KEY=sk-...
+```
+
+You can use either `CODEX_API_KEY` or `OPENAI_API_KEY`. If both are set, `CODEX_API_KEY` takes priority.
+
+### Wrong working directory
+
+Set the project directory:
+
+```env
+CODEX_CWD=/path/to/your/project
+```
+
+---
+
+## Voice Messages
+
+### "No STT provider available"
+
+No speech-to-text provider is configured. Add at least one API key:
+
+```env
+GROQ_API_KEY=gsk_...          # Recommended (fastest, free tier)
+OPENAI_API_KEY=sk-...          # Alternative
+ASSEMBLYAI_API_KEY=...         # Alternative
+```
+
+### Voice transcription is inaccurate
+
+- Speak clearly and minimize background noise
+- Try a different STT provider — Groq and OpenAI Whisper generally produce good results
+- Very short voice messages (under 1 second) may not transcribe well
+
+---
+
+## MCP Servers
+
+### "MCP not supported" error
+
+MCP is only available with OpenCode and Claude providers. Codex does not support MCP.
+
+### MCP server shows "failed" status
+
+Run `/mcp` to check the error message. Common causes:
+
+1. **Command not found**: The MCP server command isn't installed
+   ```bash
+   # Install the server package first
+   npx -y @modelcontextprotocol/server-memory
+   ```
+
+2. **Connection refused** (remote servers): The URL is wrong or the server is down
+
+3. **Permission denied**: The command doesn't have execute permissions
+
+### MCP servers disappear after restart (Claude)
+
+Claude stores MCP configs in memory. They're passed to every query but lost when the bot restarts. Re-add them after restart:
+
+```
+/mcp add memory local npx -y @modelcontextprotocol/server-memory
+```
+
+OpenCode servers persist across restarts since they're saved in the OpenCode configuration.
+
+---
+
+## Streaming
+
+### Messages appear jumpy or laggy
+
+Telegram rate limits message edits. Relay batches updates to avoid hitting limits, but on slow connections you may notice slight delays. This is normal behavior.
+
+### "Message is not modified" warnings in logs
+
+This happens when a stream update has the same content as the current message. It's harmless and can be ignored.
+
+### Very long responses get cut off
+
+Telegram messages have a 4096-character limit. Relay automatically splits long responses into multiple messages. If a response seems incomplete, it may still be generating — wait for the stream to finish.
+
+---
+
+## Model Selection
+
+### "/model sonnet" doesn't work
+
+Partial model matching searches through available models. If the match is ambiguous, try a more specific name:
+
+```
+/model anthropic/claude-sonnet-4-20250514
+```
+
+Use `/models` to see all available model IDs.
+
+### No models listed
+
+- **OpenCode**: Check that your OpenCode config has providers and models configured
+- **Claude/Codex**: Models are a static list and should always appear
+
+---
+
+## System Prompt
+
+### Changes to skill.md aren't picked up
+
+The file watcher should detect changes automatically. If it doesn't:
+
+1. Use `/system reload` to force a reload
+2. Check that the file path is correct:
+   ```env
+   SYSTEM_PROMPT_FILE=skill.md
+   ```
+3. Verify the file exists and is readable
+
+### "/system" shows "default prompt"
+
+No custom prompt file was found. Create `skill.md` in the project root or set `SYSTEM_PROMPT_FILE` to your prompt file path.
+
+---
+
+## General
+
+### Bot is slow to respond
+
+- Check your internet connection
+- The AI provider may be experiencing high load
+- Larger models (opus, o3) are slower than smaller ones (haiku, o4-mini)
+- If using OpenCode in connect mode, check the server's health
+
+### "Operation timed out"
+
+The AI took too long to respond. This can happen with complex requests. Try:
+
+- Simplifying your request
+- Using a faster model (`/model haiku` or `/model o4-mini`)
+- Breaking the task into smaller steps
+
+### Telegram message formatting looks wrong
+
+Relay sends messages in HTML format. If you see raw HTML tags, there may be an escaping issue. Report it as a bug.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@4via6/relay",
+  "version": "1.0.0",
+  "description": "Telegram bot for AI coding agents — supports OpenCode, Claude Code, and OpenAI Codex",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "relay": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "docs",
+    ".env.example",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "tsc --watch & node --watch dist/cli.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "telegram",
+    "bot",
+    "ai",
+    "coding-agent",
+    "opencode",
+    "claude",
+    "codex",
+    "mcp",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Harsh-2002/Relay"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@opencode-ai/sdk": "^1.2.15",
+    "grammy": "^1.40.1"
+  },
+  "optionalDependencies": {
+    "@anthropic-ai/claude-code": "^0.2.62",
+    "@openai/codex": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.2",
+    "typescript": "^5.0.0"
+  }
+}