TeleMux

Bidirectional Telegram integration for tmux sessions - Monitor commands, interact with agents, and stay connected to your terminal from anywhere.

Features

• One-way notifications: Send alerts to Telegram when commands complete
• Bidirectional communication: Interact with tmux sessions via Telegram
• Agent support: Create interactive agents that can receive replies
• Session routing: Messages automatically delivered to the correct tmux session
• Daemon-based: Runs as a background service in tmux
• Shell integration: Simple shell functions for easy use
• Secure: Configuration files are automatically protected (chmod 600)

Installation

Via pip (Recommended)

# Install the package
pip install telemux

# Run the interactive installer
telemux install

# Start the listener daemon
telemux start

From source

# Clone the repository
git clone https://github.com/malmazan/telemux.git
cd telemux

# Install in development mode
pip install -e .

# Run the installer
telemux install

Quick Start

1. Create a Telegram Bot

1. Open Telegram and search for @BotFather
2. Send /newbot and follow the prompts
3. Save the bot token provided

2. Install TeleMux

# Install via pip
pip install telemux

# Run the interactive installer
telemux install

The installer will:

• Check prerequisites (tmux, python3, curl)
• Validate your bot token
• Auto-detect available chats (with retry logic)
• Create configuration files
• Install shell functions
• Test the connection

3. Start the Listener

# Start the daemon
telemux start

# Check status
telemux status

# View logs
telemux logs

4. Use Shell Functions

# Send a simple notification
tg_alert "Build complete!"

# Send a message and receive replies (auto-detects tmux session name)
tg_agent "Ready to deploy to production?"
# Reply via Telegram: "session-name: yes"
# The reply appears directly in your terminal

# Get notified when a command completes
npm run build && tg_done

Commands

Control Commands

telemux start       # Start the listener daemon
telemux stop        # Stop the listener daemon
telemux restart     # Restart the listener daemon
telemux status      # Check daemon status
telemux logs        # View listener logs (tail -f)
telemux attach      # Attach to the listener tmux session
telemux cleanup     # Rotate and clean up log files
telemux doctor      # Run health check and diagnose issues
telemux install     # Run interactive installer

Shortcuts

For convenience, all commands have tg- shortcuts:

tg-start    # Same as: telemux start
tg-stop     # Same as: telemux stop
tg-status   # Same as: telemux status
tg-logs     # Same as: telemux logs

Shell Functions

After installation, these functions are available in your shell:

tg_alert

Send one-way notifications to Telegram:

tg_alert "Message text"

Examples:

# Simple notification
tg_alert "Server is ready"

# Notify when command completes
npm install && tg_alert "Dependencies installed"

# Multiline messages
tg_alert "Deploy complete
- 50 files updated
- 0 errors"

tg_agent

Send messages and receive replies via Telegram (automatically uses your tmux session name):

tg_agent "Message text"

Examples:

# Ask a question (inside a tmux session named "deploy")
tg_agent "Ready to deploy to production?"

# Wait for user response via Telegram
# User replies: "deploy: yes, proceed"
# Reply appears in your terminal

# Use in scripts (inside a tmux session named "approval")
tg_agent "Approve release v2.0?"
# Returns the session name, user responds via Telegram
# Check incoming message for approval

tg_done

Automatically notify when the previous command completes:

npm run build && tg_done

This sends a notification with:

• Command that ran
• Exit code (success/failure)
• Timestamp

Bidirectional Communication

TeleMux uses session-based routing for bidirectional communication:

Sending Messages from Terminal

# In tmux session named "deploy"
tg_agent "Should I proceed with deployment?"

This sends a message to Telegram with instructions on how to reply. The session name is automatically detected.

Replying from Telegram

Reply with the format: session-name: your message

deploy: yes, proceed with deployment

The reply is automatically routed to the correct tmux session and appears in your terminal.

Security

• Messages are routed only to existing tmux sessions
• User input is sanitized to prevent command injection
• Session names are validated before routing
• No session names are revealed in error messages

Bypass Sanitization (Advanced):

By default, all messages are sanitized using shlex.quote() to prevent command injection. If you need to send raw commands with special characters, prefix your message with !:

# Normal (sanitized) - safe for user input
session-name: echo "Hello World"

# Bypass sanitization - execute command directly and get output
session-name: !ls -la
session-name: !echo "Current directory: $(pwd)"
session-name: !git status

When using the ! prefix, TeleMux will:

1. Execute the command directly without sanitization
2. Wait 2 seconds for the command to complete
3. Capture the last 100 lines of terminal output
4. Send the output back to you via Telegram

WARNING: The ! prefix disables all security sanitization. Only use this when you control the input and understand the security implications. Malicious use could execute arbitrary commands.

Configuration

Configuration is stored in ~/.telemux/:

~/.telemux/
├── telegram_config          # Bot token and chat ID (chmod 600)
├── telegram_listener.log    # Listener daemon logs
├── telegram_errors.log      # Error logs
├── message_queue/           # Message routing data
│   ├── outgoing.log        # Sent messages
│   ├── incoming.log        # Received messages
│   └── archive/            # Rotated logs
└── shell_functions.sh       # Shell integration functions

Environment Variables

You can override configuration with environment variables:

export TELEMUX_TG_BOT_TOKEN="your-bot-token"
export TELEMUX_TG_CHAT_ID="your-chat-id"
export TELEMUX_LOG_LEVEL="DEBUG"  # DEBUG, INFO, WARNING, ERROR

Log Management

Logs are automatically rotated when they exceed 10MB:

# Manual log rotation
telemux cleanup

# Install automatic monthly cleanup
telemux cleanup --install-cron

Archives are stored in ~/.telemux/message_queue/archive/ and compressed with gzip.

Troubleshooting

Run Health Check

telemux doctor

This checks:

• Prerequisites (tmux, python3)
• Configuration files
• Telegram bot connection
• Listener daemon status
• Log files

Common Issues

Listener won't start:

# Check if it's already running
telemux status

# View logs for errors
telemux logs

# Restart the listener
telemux restart

Messages not being received:

# Check listener status
telemux status

# Verify configuration
cat ~/.telemux/telegram_config

# Test bot connection
telemux doctor

Shell functions not available:

# Reload your shell configuration
source ~/.zshrc  # or ~/.bashrc

# Verify functions are sourced
type tg_alert

Examples

Long-Running Build Notification

#!/bin/bash
# Build script with notification

echo "Starting build..."
tg_alert "Build started for project-x"

npm run build
if [ $? -eq 0 ]; then
    tg_alert "Build succeeded!"
else
    tg_alert "Build failed! Check logs."
fi

Interactive Deployment Agent

#!/bin/bash
# Deployment with approval (run in tmux session named "deploy")

tg_agent "Ready to deploy v2.0 to production?"

# User responds via Telegram: "deploy: yes"
# Response appears in terminal

read -p "Proceed with deployment? " response
if [[ "$response" == *"yes"* ]]; then
    ./deploy.sh
    tg_alert "Deployment complete!"
fi

Multi-Step Workflow

#!/bin/bash
# Complex workflow with multiple checkpoints (run in tmux session named "migration")

tg_alert "Starting migration workflow..."

# Step 1: Backup
tg_agent "Backup database before migration?"
# Wait for approval...

# Step 2: Migration
./run-migration.sh && tg_done

# Step 3: Verification
tg_agent "Verify migration results?"
# Wait for verification...

tg_alert "Migration workflow complete!"

Development

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=telemux --cov-report=term-missing

Project Structure

telemux/
├── telemux/
│   ├── __init__.py       # Package initialization
│   ├── cli.py            # Main CLI entry point
│   ├── control.py        # Daemon control (start, stop, status)
│   ├── listener.py       # Telegram listener daemon
│   ├── installer.py      # Interactive installer
│   ├── cleanup.py        # Log rotation and cleanup
│   ├── config.py         # Configuration management
│   └── shell_functions.sh # Shell integration
├── examples/             # Example scripts
├── tests/               # Test suite
├── pyproject.toml       # Package metadata and dependencies
├── MANIFEST.in          # Package file manifest
└── README.md            # This file

Requirements

• Python 3.7+
• tmux
• curl
• requests library (automatically installed)

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Changelog

See CHANGELOG.md for version history.

Support

• GitHub Issues: https://github.com/malmazan/telemux/issues
• Documentation: https://github.com/malmazan/telemux

Credits

Created by Marco Almazan

Related Projects

• tmux - Terminal multiplexer
• python-telegram-bot - Telegram Bot API wrapper