omo-tg

Control your AI coding sessions from Telegram.

omo-tg is a self-hosted Telegram Mini App and bot that connects to OpenCode and omo-pulse. Check live session status, send prompts, abort stuck tasks, and track token usage from your phone or desktop without touching your IDE.

Features

• Telegram Mini App - Full dashboard inside Telegram with responsive UI
• Bot Commands - /start, /status, /sessions for quick access
• Session Interaction - Send prompts, answer questions, abort sessions directly from Telegram
• Real-time Status Monitoring - Live updates from omo-pulse API
• Pinned Status Message - Automatic notifications via omo-pulse notification module

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Telegram                                  │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Mini App (Webview)  │  Bot Commands  │  Notifications│  │
│  └─────────────────────────────────────────────────────┘    │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTPS (Webhook)
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                    omo-tg (:4400)                            │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Hono Server        │  React UI     │  Bot Handler  │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────┬────────────────────────────┬──────────────┘
                  │                            │
                  ▼                            ▼
    ┌──────────────────────┐      ┌──────────────────────┐
    │   omo-pulse (:4300)  │      │   OpenCode (:4096)   │
    │   Monitoring API     │      │   Session API        │
    └──────────────────────┘      └──────────────────────┘

Prerequisites

• Bun >= 1.1.0 (bun --version)
• omo-pulse running (see omo-pulse repository)
• OpenCode server running (opencode serve on port 4096)
• Telegram Bot Token from @BotFather
• HTTPS for production (Cloudflare Tunnel, ngrok, or VPS with SSL)

Quick Start

1. Clone and install

   git clone https://github.com/ezotoff/omo-tg.git
   cd omo-tg
   bun install

2. Configure environment

   cp .env.example .env
   # Edit .env with your Telegram bot token

3. Start omo-pulse (in separate terminal)

   # In omo-pulse directory
   bun run dev

4. Start omo-tg

   bun run dev

5. Set up HTTPS (see below)

6. Configure BotFather (see below)

Configuration

Environment Variable	Default	Description
OMO_PULSE_URL	http://localhost:4300	omo-pulse API URL for monitoring data
OPENCODE_URL	http://localhost:4096	OpenCode server URL for session interaction
TELEGRAM_BOT_TOKEN	(required)	Telegram bot token from @BotFather
TELEGRAM_CHAT_ID	(optional)	Specific chat ID for bot commands
OMO_TG_PORT	4400	omo-tg server port
OMO_TG_PUBLIC_URL	(required for production)	Public HTTPS URL for Telegram webhook
OPENCODE_USERNAME	(optional)	OpenCode server username (if password-protected)
OPENCODE_PASSWORD	(optional)	OpenCode server password (if password-protected)

HTTPS Setup

Telegram Mini Apps require HTTPS in production. Choose one option:

Cloudflare Tunnel (Recommended)

1. Install cloudflared:

   # macOS
   brew install cloudflare/cloudflare/cloudflared
   
   # Linux
   wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
   sudo dpkg -i cloudflared-linux-amd64.deb

2. Authenticate:

   cloudflared tunnel login

3. Create tunnel:

   bun run tunnel
   # Or manually: cloudflared tunnel create omo-tg

4. Route DNS:

   cloudflared tunnel route dns omo-tg your-subdomain.example.com

5. Run tunnel:

   cloudflared tunnel run omo-tg

6. Set OMO_TG_PUBLIC_URL=https://your-subdomain.example.com in .env

ngrok (Quick Testing)

1. Install ngrok: https://ngrok.com/download
2. Start tunnel:

   ngrok http 4400

3. Use the provided HTTPS URL (note: free URLs change on restart)
4. Set OMO_TG_PUBLIC_URL to the ngrok URL

Self-hosted (VPS)

1. Deploy omo-tg to a VPS
2. Configure reverse proxy (nginx example):

   server {
       server_name your-domain.example.com;
       
       location / {
           proxy_pass http://localhost:4400;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection 'upgrade';
           proxy_set_header Host $host;
           proxy_cache_bypass $http_upgrade;
       }
       
       listen 443 ssl;
       ssl_certificate /path/to/fullchain.pem;
       ssl_certificate_key /path/to/privkey.pem;
   }

3. Set OMO_TG_PUBLIC_URL=https://your-domain.example.com

BotFather Setup

To configure the Telegram Mini App menu button:

1. Send /mybots to @BotFather
2. Select your bot → Bot Settings → Menu Button
3. Choose Configure menu button
4. Enter your public HTTPS URL (from Cloudflare/ngrok/VPS)
5. Save changes

Users will now see a "Open Dashboard" button in your bot's chat.

Relationship with omo-pulse

omo-tg and omo-pulse work together but serve different purposes:

Component	Purpose	Required?
omo-tg	Telegram interface for interaction	Yes (this project)
omo-pulse	Monitoring dashboard + API	Yes (for monitoring data)
OpenCode	AI coding sessions	Yes (for session interaction)

Key points:

• omo-tg provides the Telegram Mini App and bot commands
• omo-pulse provides monitoring data via API (/api/projects)
• Both use the same Telegram bot token (no conflict)
• omo-tg connects directly to OpenCode for session interaction
• Pinned status notifications come from omo-pulse, not omo-tg

Limitations

• Mini App Pausing: Telegram Mini Apps pause when the Telegram app is minimized (no background updates)
• Notifications: Pinned status notifications are handled by omo-pulse, not omo-tg
• HTTPS Required: Production Telegram Mini Apps require HTTPS
• Network Access: OpenCode server must be reachable from omo-tg server
• Bot Token: One bot token shared between omo-tg and omo-pulse notifications

Tech Stack

Layer	Technology
Runtime	Bun >= 1.1.0
Language	TypeScript (strict mode)
UI Framework	React 18
Build Tool	Vite 5
Server Framework	Hono
CSS	Plain CSS (no frameworks)
Package Manager	Bun

Development

# Development server (UI + API)
bun run dev

# UI-only development
bun run dev:ui

# Production build
bun run build

# Production server
bun run start

# Cloudflare Tunnel setup
bun run tunnel

License

MIT