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.

Telegram Commands

Send these commands directly to your Telegram bot:

• capture - Capture and send back the last 100 lines of your active session
• capture on - Enable auto-capture (waits 5 seconds after each message, then sends output)
• capture off - Disable auto-capture
• capture status - Check if auto-capture is enabled

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_TG_USER_ID="your-user-id"# Optional: restrict control to specific userexport 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 configurationsource~/.zshrc # or ~/.bashrc# Verify functions are sourcedtype tg_alert

Examples

Long-Running Build Notification

#!/bin/bash# Build script with notificationecho"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 terminalread -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