Telegram TMux Relay

Control any tmux session from your phone via Telegram. A persistent relay that streams terminal output to Telegram in real-time.

Features

• Bidirectional communication - Send commands to tmux, receive output in Telegram
• Persistent relay - Continuously streams terminal output (not just request/response)
• Session switching - Control multiple tmux sessions from one bot
• Rate limiting - Built-in flood protection for Telegram API
• Clean output - Filters terminal noise (separators, prompts, etc.)
• Secure - Lock to specific Telegram user IDs

Installation

# Clone the repo
git clone https://github.com/YOUR_USERNAME/telegram-tmux-relay.git
cd telegram-tmux-relay

# Install dependencies
pip install python-telegram-bot

# Or with requirements file
pip install -r requirements.txt

Setup

1. Create a Telegram Bot

1. Message @BotFather on Telegram
2. Send /newbot and follow the prompts
3. Save your bot token

2. Get Your Telegram User ID

1. Message @userinfobot on Telegram
2. It will reply with your user ID

3. Create a tmux session

tmux new-session -s main

4. Run the relay

export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export ALLOWED_USER_IDS="your_user_id_here"
export DEFAULT_TMUX_SESSION="main"

python relay.py

Or run in the background:

tmux new-session -d -s relay "TELEGRAM_BOT_TOKEN=xxx ALLOWED_USER_IDS=123 python relay.py"

Usage

Commands

Command	Description
/start	Activate the relay
/screen	Get current terminal view
/sessions	List all tmux sessions
/switch <name>	Switch to a different session
/mute	Pause the relay
/unmute	Resume the relay

Sending Input

Just type any message and it will be sent to the active tmux session as if you typed it in the terminal.

Environment Variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Your Telegram bot token from BotFather
ALLOWED_USER_IDS	No	Comma-separated list of allowed Telegram user IDs. If not set, anyone can use the bot (not recommended)
DEFAULT_TMUX_SESSION	No	Default tmux session to connect to (default: main)

Security

Important: This bot gives full terminal access to whoever can message it. Always:

1. Set ALLOWED_USER_IDS to restrict access
2. Never share your bot token
3. Be aware that anyone with access can run commands on your machine

How It Works

Telegram → Bot → tmux send-keys → Terminal
                                      ↓
Telegram ← Bot ← tmux capture-pane ←──┘

The bot runs a background watcher that:

1. Polls the tmux pane every 2 seconds
2. Detects new output by diffing with previous state
3. Filters out terminal noise
4. Batches and sends clean output to Telegram

Example: Mobile AI Coding Assistant

One powerful use case is pairing this with AI coding assistants that run in the terminal (like Claude Code, Aider, etc.). This gives you a mobile interface to your AI dev environment:

Setup

# Start a tmux session for your AI assistant
tmux new-session -s coding

# In that session, start your AI coding tool
claude  # or aider, or any terminal-based AI

# In another terminal, run the relay pointed at that session
export TELEGRAM_BOT_TOKEN="your_token"
export ALLOWED_USER_IDS="your_id"
export DEFAULT_TMUX_SESSION="coding"
python relay.py

Usage

Now from Telegram you can:

• Send coding questions and get responses
• Ask the AI to read/write files on your server
• Run commands through the AI
• Review code changes
• All from your phone!

You (Telegram): "Hey, can you check if there are any TypeScript errors in the project?"

AI (via relay): "I'll run the TypeScript compiler to check for errors...
Found 3 errors in src/utils.ts:
- Line 42: Type 'string' is not assignable to type 'number'
..."

This effectively turns Telegram into a mobile interface for your AI coding assistant - no API costs beyond your existing subscription, just terminal relay magic.

License

MIT License - see LICENSE