@4via6/relay 1.0.0

package/.env.example

@@ -0,0 +1,50 @@
+# Telegram
+BOT_TOKEN=your-telegram-bot-token
+ALLOWED_USER_ID=your-telegram-user-id
+
+# Provider selection: "opencode" | "claude" | "codex"
+PROVIDER=opencode
+
+# --- OpenCode provider ---
+OPENCODE_MODE=start                  # "start" (spawn server) or "connect" (remote URL)
+OPENCODE_URL=http://localhost:4096   # used when MODE=connect
+OPENCODE_HOSTNAME=127.0.0.1         # used when MODE=start
+OPENCODE_PORT=4096                   # used when MODE=start
+OPENCODE_MODEL=                      # e.g. "anthropic/claude-sonnet-4-20250514"
+
+# --- Claude Code provider ---
+# ANTHROPIC_API_KEY=sk-ant-...       # required for PROVIDER=claude
+# CLAUDE_MODEL=sonnet                # "sonnet" | "opus" | "haiku"
+# CLAUDE_PERMISSION_MODE=acceptEdits # Claude permission mode
+# CLAUDE_CWD=                        # working directory (default: process.cwd())
+
+# --- Codex provider ---
+# CODEX_API_KEY=sk-...               # required for PROVIDER=codex (or use OPENAI_API_KEY)
+# CODEX_MODEL=o3                     # "o3" | "o4-mini" etc.
+# CODEX_CWD=                         # working directory (default: process.cwd())
+
+# Bot mode: "polling" (default) or "webhook"
+BOT_MODE=polling
+# WEBHOOK_URL=https://example.com/bot   # required when BOT_MODE=webhook
+# WEBHOOK_PORT=3000                      # HTTP server port (default: 3000)
+# WEBHOOK_SECRET=your-secret-token       # optional secret for webhook verification
+
+# Data directory for persisted state (default: .relay/ in project root)
+# RELAY_DATA_DIR=.relay
+
+# Streaming (progressive message editing — supported by all providers)
+STREAMING_ENABLED=false
+STREAM_EDIT_INTERVAL_MS=2000
+
+# Prompt timeout (milliseconds) — max time to wait for a provider response
+PROMPT_TIMEOUT_MS=300000  # 5 minutes
+
+# System prompt — loaded from file and prepended to every message
+# Default built-in prompt is used if no file exists
+# SYSTEM_PROMPT_FILE=skill.md  # default: looks for skill.md in project root
+
+# Voice STT — set one or more; cheapest available is auto-selected
+# STT_PROVIDER=auto  # "openai" | "groq" | "assemblyai" | "auto" (default)
+GROQ_API_KEY=
+OPENAI_API_KEY=
+ASSEMBLYAI_API_KEY=

package/README.md

@@ -0,0 +1,253 @@
+# Relay
+
+Telegram bot for managing AI coding agents remotely. Supports [OpenCode](https://github.com/opencode-ai/opencode), [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), and [OpenAI Codex](https://github.com/openai/codex).
+
+## Features
+
+- **Multi-provider** -- switch between OpenCode, Claude Code, and Codex with a single env var
+- **Text, voice, photo, and file input** -- send messages in any format
+- **File output** -- receive screenshots, generated files, and artifacts as Telegram attachments (OpenCode)
+- **Streaming responses** -- progressive message editing for real-time output
+- **Session management** -- create, switch, fork, delete, and list sessions
+- **Dynamic model selection** -- models fetched from provider APIs, always up to date
+- **MCP servers** -- add, remove, and monitor MCP servers at runtime (OpenCode, Claude)
+- **Shell access** -- run commands on the coding agent's machine
+- **Voice transcription** -- Groq, OpenAI, or AssemblyAI speech-to-text
+- **Custom system prompts** -- load from file, hot-reload on change
+- **File operations** -- read, find, search, and browse project files (all providers)
+- **Code diffs** -- view git diffs from sessions (all providers)
+- **State persistence** -- sessions, model selection, and MCP configs survive restarts
+- **Webhook mode** -- deploy with webhooks for lower latency in production
+- **Large file support** -- text files up to 500KB fully included, larger files chunked
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [Getting Started](docs/getting-started.md) | Installation, prerequisites, first steps |
+| [Configuration](docs/configuration.md) | All environment variables and options |
+| [Providers](docs/providers.md) | Detailed setup for each provider |
+| [Commands](docs/commands.md) | Full command reference with examples |
+| [Features](docs/features.md) | Streaming, file attachments, voice, MCP, models |
+| [Troubleshooting](docs/troubleshooting.md) | Common issues and solutions |
+
+## Install
+
+### From npm
+
+```bash
+npm install -g relay
+```
+
+Then create a `.env` file in your working directory (see [Configuration](docs/configuration.md)):
+
+```bash
+curl -O https://raw.githubusercontent.com/Harsh-2002/relay/main/.env.example
+# Edit .env with your BOT_TOKEN, ALLOWED_USER_ID, and provider config
+relay
+```
+
+### From source
+
+```bash
+git clone https://github.com/Harsh-2002/relay.git
+cd relay
+npm install
+npm run build
+cp .env.example .env
+# Edit .env with your BOT_TOKEN, ALLOWED_USER_ID, and provider config
+npm start
+```
+
+### With npx (no install)
+
+```bash
+npx relay
+```
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org/) >= 18 (or [Bun](https://bun.sh/))
+- A Telegram bot token (from [@BotFather](https://t.me/BotFather))
+- Provider credentials (see below)
+
+## Providers
+
+Set `PROVIDER` in `.env` to select your coding agent backend.
+
+| Provider | `PROVIDER=` | Required env vars | Install |
+|----------|-------------|-------------------|---------|
+| OpenCode | `opencode` | `OPENCODE_MODE` | included |
+| Claude Code | `claude` | `ANTHROPIC_API_KEY` | `npm install @anthropic-ai/claude-code` |
+| OpenAI Codex | `codex` | `CODEX_API_KEY` or `OPENAI_API_KEY` | `npm install @openai/codex` |
+
+### OpenCode
+
+```env
+PROVIDER=opencode
+OPENCODE_MODE=start           # "start" (spawn server) or "connect" (remote URL)
+OPENCODE_URL=http://localhost:4096
+```
+
+### Claude Code
+
+```env
+PROVIDER=claude
+ANTHROPIC_API_KEY=sk-ant-...
+CLAUDE_MODEL=sonnet           # use /models to see all available
+CLAUDE_PERMISSION_MODE=acceptEdits
+```
+
+### OpenAI Codex
+
+```env
+PROVIDER=codex
+CODEX_API_KEY=sk-...
+CODEX_MODEL=o3                # use /models to see all available
+```
+
+## Commands
+
+### Chat
+Send any text message, voice note, photo, or file to chat with the AI. File attachments from the AI (screenshots, generated files) are automatically sent back as Telegram documents or photos.
+
+### Sessions
+| Command | Description |
+|---------|-------------|
+| `/new` | Create a new session |
+| `/sessions` | List all sessions |
+| `/switch <id>` | Switch to a session |
+| `/delete <id>` | Delete a session |
+| `/current` | Show active session |
+| `/fork [messageId]` | Fork the current session |
+
+### Monitor
+| Command | Description |
+|---------|-------------|
+| `/todo` | View AI task checklist (OpenCode) |
+| `/diff` | Session code changes summary |
+| `/diff full` | Download full diff |
+
+### Files
+| Command | Description |
+|---------|-------------|
+| `/read <path>` | Read a file |
+| `/find <query>` | Find files by name |
+| `/search <pattern>` | Search file contents |
+| `/symbols <query>` | Find code symbols (OpenCode) |
+| `/status` | Git file status |
+
+### History
+| Command | Description |
+|---------|-------------|
+| `/history` | View conversation history |
+| `/summarize` | Summarize the session |
+| `/revert` | Undo last AI change |
+| `/abort` | Cancel running operation |
+| `/share` | Share session (OpenCode) |
+
+### Shell
+| Command | Description |
+|---------|-------------|
+| `/shell <cmd>` | Run a shell command |
+| `/cmd <command>` | Run an OpenCode command |
+| `/commands` | List available commands |
+
+### Models
+| Command | Description |
+|---------|-------------|
+| `/models` | List available models with capabilities |
+| `/model <provider/model>` | Set the AI model |
+| `/model <name>` | Set model by partial match |
+
+Models show capability badges: `[reasoning]` for thinking/reasoning support, `[vision]` for image input, and `[active]` for the currently selected model.
+
+### MCP (OpenCode, Claude)
+| Command | Description |
+|---------|-------------|
+| `/mcp` | Show MCP server status |
+| `/mcp add <name> local <command...>` | Add a local MCP server |
+| `/mcp add <name> remote <url>` | Add a remote MCP server |
+| `/mcp remove <name>` | Remove an MCP server |
+
+MCP servers extend the AI's capabilities with additional tools (browsers, databases, APIs). OpenCode supports full runtime management; Claude persists MCP config to disk and restores it on restart.
+
+### Settings
+| Command | Description |
+|---------|-------------|
+| `/system` | View system prompt |
+| `/system reload` | Reload system prompt |
+| `/health` | Server status (with reasoning badge) |
+| `/config` | Show configuration |
+| `/providers` | List available providers |
+| `/agents` | List available agents |
+| `/tools` | Available tools |
+| `/project` | Project info |
+| `/git` | Git branch and status |
+| `/help` | Show all commands |
+
+## Voice / STT
+
+Configure one or more speech-to-text providers for voice message support. The cheapest available provider is auto-selected.
+
+```env
+GROQ_API_KEY=...          # Groq Whisper (fastest, free tier)
+OPENAI_API_KEY=...        # OpenAI Whisper
+ASSEMBLYAI_API_KEY=...    # AssemblyAI
+```
+
+## System Prompt
+
+The bot loads a system prompt from `skill.md` in the project root (or the path set in `SYSTEM_PROMPT_FILE`). If the file doesn't exist, a default prompt is used. The file is watched for changes and reloaded automatically. Use `/system reload` to force a reload.
+
+## Architecture
+
+```
+src/
+  providers/
+    types.ts       -- Provider interface, capabilities, MCP/model types
+    index.ts       -- Provider factory (selects based on PROVIDER env var)
+    opencode.ts    -- OpenCode SDK provider
+    claude.ts      -- Claude Code / Agent SDK provider
+    codex.ts       -- OpenAI Codex SDK provider
+  commands/
+    chat.ts        -- Text message handler
+    session.ts     -- Session management commands
+    media.ts       -- Photo, voice, audio, file handlers
+    admin.ts       -- Health, config, model, models, help commands
+    monitor.ts     -- Todo, diff, fork commands
+    files.ts       -- File read, find, search commands
+    history.ts     -- History, revert, share commands
+    shell.ts       -- Shell and command execution
+    mcp.ts         -- MCP server management
+  utils/
+    store.ts       -- JSON file-backed persistence (.relay/)
+    stream.ts      -- Streaming response handler
+    files.ts       -- Outbound file attachment handling
+    chunker.ts     -- Telegram message chunking
+    errors.ts      -- Error formatting
+    html.ts        -- HTML escaping for Telegram
+    media.ts       -- File upload/download
+    stt.ts         -- Speech-to-text
+    system-prompt.ts -- System prompt loading
+    timeout.ts     -- Prompt timeout utility
+```
+
+Each provider implements the `Provider` interface with a `capabilities` object declaring which features it supports. Commands check capabilities and show appropriate messages when a feature isn't available.
+
+### Provider Capabilities
+
+| Capability | OpenCode | Claude | Codex |
+|-----------|----------|--------|-------|
+| Streaming | yes | yes | yes |
+| File output | yes | no | no |
+| MCP management | yes | yes | no |
+| Model listing | dynamic | dynamic | dynamic |
+| Session management | full | limited | limited |
+| File operations | yes | yes | yes |
+| Code diffs | yes | yes | yes |
+| State persistence | yes | yes | yes |
+
+## License
+
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,3 @@
+import type { Context, NextFunction } from "grammy";
+export declare function isAuthConfigured(): boolean;
+export declare function authMiddleware(ctx: Context, next: NextFunction): Promise<void>;

package/dist/auth.js

@@ -0,0 +1,32 @@
+// Parse ALLOWED_USER_ID — fail-secure: NaN means "block all"
+const raw = process.env.ALLOWED_USER_ID;
+const allowedUserId = raw ? Number(raw) : NaN;
+// Simple in-memory rate limiter: max requests per minute per user
+const RATE_LIMIT = 30;
+const rateBuckets = new Map();
+export function isAuthConfigured() {
+    return !isNaN(allowedUserId) && allowedUserId > 0;
+}
+export async function authMiddleware(ctx, next) {
+    // Fail-secure: if ALLOWED_USER_ID is not set or invalid, block everyone
+    if (!isAuthConfigured()) {
+        await ctx.reply("Bot is misconfigured — ALLOWED_USER_ID is not set.");
+        return;
+    }
+    const userId = ctx.from?.id;
+    if (userId !== allowedUserId) {
+        await ctx.reply("Unauthorized.");
+        return;
+    }
+    // Rate limiting
+    const now = Date.now();
+    const bucket = (rateBuckets.get(userId) ?? []).filter((t) => now - t < 60_000);
+    if (bucket.length >= RATE_LIMIT) {
+        await ctx.reply("Too many requests — wait a moment.");
+        return;
+    }
+    bucket.push(now);
+    rateBuckets.set(userId, bucket);
+    await next();
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAEA,6DAA6D;AAC7D,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;AACxC,MAAM,aAAa,GAAG,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;AAE9C,kEAAkE;AAClE,MAAM,UAAU,GAAG,EAAE,CAAC;AACtB,MAAM,WAAW,GAAG,IAAI,GAAG,EAAoB,CAAC;AAEhD,MAAM,UAAU,gBAAgB;IAC9B,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,CAAC;AACpD,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,GAAY,EAAE,IAAkB;IACnE,wEAAwE;IACxE,IAAI,CAAC,gBAAgB,EAAE,EAAE,CAAC;QACxB,MAAM,GAAG,CAAC,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACtE,OAAO;IACT,CAAC;IAED,MAAM,MAAM,GAAG,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC;IAC5B,IAAI,MAAM,KAAK,aAAa,EAAE,CAAC;QAC7B,MAAM,GAAG,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QACjC,OAAO;IACT,CAAC;IAED,gBAAgB;IAChB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,CAAC,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IAC/E,IAAI,MAAM,CAAC,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,GAAG,CAAC,KAAK,CAAC,oCAAoC,CAAC,CAAC;QACtD,OAAO;IACT,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjB,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEhC,MAAM,IAAI,EAAE,CAAC;AACf,CAAC"}

package/dist/bot.d.ts

@@ -0,0 +1,2 @@
+import { Bot } from "grammy";
+export declare function createBot(token: string): Bot;

package/dist/bot.js

@@ -0,0 +1,14 @@
+import { Bot } from "grammy";
+import { authMiddleware } from "./auth.js";
+import { registerCommands } from "./commands/index.js";
+export function createBot(token) {
+    const bot = new Bot(token);
+    bot.use(authMiddleware);
+    registerCommands(bot);
+    bot.catch((err) => {
+        const e = err.error;
+        console.error("Bot error:", e instanceof Error ? e.message : String(e));
+    });
+    return bot;
+}
+//# sourceMappingURL=bot.js.map

package/dist/bot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bot.js","sourceRoot":"","sources":["../src/bot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,UAAU,SAAS,CAAC,KAAa;IACrC,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAE3B,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IACxB,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAEtB,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;QAChB,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;QACpB,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC,CAAC,CAAC;IAEH,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./index.js";

package/dist/cli.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./index.js";
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,YAAY,CAAC"}

package/dist/commands/admin.d.ts

@@ -0,0 +1,2 @@
+import type { Bot } from "grammy";
+export declare function registerAdminCommands(bot: Bot): void;