telemux 1.0.1__py3-none-any.whl

telemux-1.0.1.dist-info/METADATA

@@ -0,0 +1,479 @@
+Metadata-Version: 2.4
+Name: telemux
+Version: 1.0.1
+Summary: Bidirectional Telegram integration for tmux sessions - monitor commands and interact with agents
+Author-email: Marco Almazan <marco@example.com>
+License: MIT
+Project-URL: Homepage, https://github.com/malmazan/telemux
+Project-URL: Repository, https://github.com/malmazan/telemux
+Project-URL: Issues, https://github.com/malmazan/telemux/issues
+Keywords: telegram,tmux,notifications,monitoring,agent,automation
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: System :: Monitoring
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests<3.0.0,>=2.25.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.1; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# 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)
+
+```bash
+# Install the package
+pip install telemux
+
+# Run the interactive installer
+telemux install
+
+# Start the listener daemon
+telemux start
+```
+
+### From source
+
+```bash
+# 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](https://t.me/BotFather)
+2. Send `/newbot` and follow the prompts
+3. Save the bot token provided
+
+### 2. Install TeleMux
+
+```bash
+# 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
+
+```bash
+# Start the daemon
+telemux start
+
+# Check status
+telemux status
+
+# View logs
+telemux logs
+```
+
+### 4. Use Shell Functions
+
+```bash
+# Send a simple notification
+tg_alert "Build complete!"
+
+# Send a message and receive replies
+tg_agent "deploy-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
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+tg_alert "Message text"
+```
+
+**Examples:**
+
+```bash
+# 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:
+
+```bash
+tg_agent "agent-name" "Message text"
+```
+
+**Examples:**
+
+```bash
+# Ask a question
+tg_agent "deploy-agent" "Ready to deploy to production?"
+
+# Wait for user response via Telegram
+# User replies: "session-name: yes, proceed"
+# Reply appears in your terminal
+
+# Use in scripts
+response=$(tg_agent "approval-agent" "Approve release v2.0?")
+if [[ "$response" == *"yes"* ]]; then
+    ./deploy.sh
+fi
+```
+
+### `tg_done`
+
+Automatically notify when the previous command completes:
+
+```bash
+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
+
+```bash
+# In tmux session named "deploy"
+tg_agent "deploy-check" "Should I proceed with deployment?"
+```
+
+This sends a message to Telegram with instructions on how to reply.
+
+### 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
+
+## 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:
+
+```bash
+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:
+
+```bash
+# 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
+
+```bash
+telemux doctor
+```
+
+This checks:
+- Prerequisites (tmux, python3)
+- Configuration files
+- Telegram bot connection
+- Listener daemon status
+- Log files
+
+### Common Issues
+
+**Listener won't start:**
+```bash
+# Check if it's already running
+telemux status
+
+# View logs for errors
+telemux logs
+
+# Restart the listener
+telemux restart
+```
+
+**Messages not being received:**
+```bash
+# Check listener status
+telemux status
+
+# Verify configuration
+cat ~/.telemux/telegram_config
+
+# Test bot connection
+telemux doctor
+```
+
+**Shell functions not available:**
+```bash
+# Reload your shell configuration
+source ~/.zshrc  # or ~/.bashrc
+
+# Verify functions are sourced
+type tg_alert
+```
+
+## Examples
+
+### Long-Running Build Notification
+
+```bash
+#!/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
+
+```bash
+#!/bin/bash
+# Deployment with approval
+
+tg_agent "deploy-agent" "Ready to deploy v2.0 to production?"
+
+# User responds via Telegram: "session-name: 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
+
+```bash
+#!/bin/bash
+# Complex workflow with multiple checkpoints
+
+tg_alert "Starting migration workflow..."
+
+# Step 1: Backup
+tg_agent "migration-agent" "Backup database before migration?"
+# Wait for approval...
+
+# Step 2: Migration
+./run-migration.sh && tg_done
+
+# Step 3: Verification
+tg_agent "migration-agent" "Verify migration results?"
+# Wait for verification...
+
+tg_alert "Migration workflow complete!"
+```
+
+## Development
+
+### Running Tests
+
+```bash
+# 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](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](https://github.com/tmux/tmux) - Terminal multiplexer
+- [python-telegram-bot](https://github.com/python-telegram-bot/python-telegram-bot) - Telegram Bot API wrapper

telemux-1.0.1.dist-info/RECORD

@@ -0,0 +1,14 @@
+telemux/__init__.py,sha256=NPsaDXPUdx3Vr5f-sAEwO4NCCsj1xSFrkFPdIR2zPBE,528
+telemux/cleanup.py,sha256=bR3xRPnDieciLae1mosvZIqPb4w4esByVwLHFz-pV4I,5157
+telemux/cli.py,sha256=FyxN0KT0z0JhfLZgATfUbaBQ10BTfRYtUdfvOFdtQ3E,2571
+telemux/config.py,sha256=tRmrbgW-7tBpLhSSh21H_cdKOlYh2dFX-KFvlldGcnQ,2128
+telemux/control.py,sha256=VdmmqnfehGhYNBWpITvqxGO4IXaWf2IFurNjF-4IjAI,9410
+telemux/installer.py,sha256=tOtZGWAkKmY1NS2vt27QK_kNvh7t49Jngua9D_pO6nM,13667
+telemux/listener.py,sha256=7RCexHSgzqoRVmDMto3WChHtyRKct59VTcyOl376jeM,11897
+telemux/shell_functions.sh,sha256=j-uDRKlvEd_tVU4PmsMuf8NKmKUtnCd6VRZ3aELcio8,3476
+telemux-1.0.1.dist-info/licenses/LICENSE,sha256=dDp-Qt-v7Zi0aUHsgKxLdeWcP-qO-BtCmtP5T43Z6VI,1070
+telemux-1.0.1.dist-info/METADATA,sha256=1B0LX2PFtZZ0CS-XEvoWu-nWUQUEeY--IYheT_w_trA,10926
+telemux-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+telemux-1.0.1.dist-info/entry_points.txt,sha256=mxK4w1flc7W4lj4tAHyDr4k_KOWmwmuqXw3cWmMZ7Dw,527
+telemux-1.0.1.dist-info/top_level.txt,sha256=VSZ88IJhbt7XXwzMYBbFQMuXy-Q01JkzFXKn8ELixYw,8
+telemux-1.0.1.dist-info/RECORD,,

telemux-1.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

telemux-1.0.1.dist-info/entry_points.txt

@@ -0,0 +1,15 @@
+[console_scripts]
+telemux = telemux.cli:main
+telemux-attach = telemux.control:attach
+telemux-cleanup = telemux.cleanup:main
+telemux-doctor = telemux.control:doctor
+telemux-install = telemux.installer:main
+telemux-logs = telemux.control:logs
+telemux-restart = telemux.control:restart
+telemux-start = telemux.control:start
+telemux-status = telemux.control:status
+telemux-stop = telemux.control:stop
+tg-logs = telemux.control:logs
+tg-start = telemux.control:start
+tg-status = telemux.control:status
+tg-stop = telemux.control:stop

telemux-1.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Marco Almazan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telemux-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+telemux