tmagent

tmagent is an interactive command-line interface (CLI) tool for managing tmate sessions. The main use case is to quickly create and share tmate sessions, making it easy to connect to a session from a mobile device or share it with others for remote pair programming and technical support.

Features

• 🚀 Easy Session Management: Create, view, and destroy tmate sessions with an intuitive interface
• 🎨 Color-coded Sessions: Choose from 7 different colors to easily identify your sessions
• 🔗 SSH Link Display: Automatically retrieves and displays read-write and read-only SSH links
• 📱 QR Code Generation: Generates QR codes for quick mobile access to your sessions
• 🤖 AI Client Integration: Automatically detects and integrates with popular AI clients (Gemini, Claude, Qwen, Opencode)
• 📢 Telegram Notifications: Send session information directly to Telegram (when configured)
• 🌍 Internationalization: Available in English (more languages can be added)

Screenshots

Create new session

Select AI agent

QR codes

Manage sessions

Telegram notification

Installation

Prerequisites

• Python 3.10 or higher
• tmate installed and available in your PATH

Install from PyPI

pip install tmagent

Install from Source

git clone https://github.com/aabee-tech/tmagent.git
cd tmagent
pip install -e .

Usage

After installation, simply run:

tmagent

The interactive menu will guide you through all available options:

1. Create new session: Start a new tmate session with your preferred color and AI client
2. Manage existing session: Connect to, view links for, or destroy existing sessions
3. Kill all sessions: Terminate all active tmate sessions at once

Telegram Integration

To enable Telegram notifications, set the following environment variables:

export TELEGRAM_BOT_TOKEN="your_bot_token_here"
export TELEGRAM_CHAT_ID="your_chat_id_here"

When creating a new session, you'll be prompted to send a notification if these variables are set.

Development

Prerequisites

• Python 3.10 or higher
• tmate

Setup Development Environment

# Clone the repository
git clone https://github.com/aabee-tech/tmagent.git
cd tmagent

# Install dependencies
pip install -e .[dev]

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=src/tmate_cli

# Run tests with coverage report
pytest --cov=src/tmate_cli --cov-report=html

Code Quality Checks

# Run linter
ruff check .

# Run type checker
mypy src/tmate_cli

# Run security scanner
bandit -r src/tmate_cli

Building and Publishing

# Build the package
./scripts/build.sh

# Publish to PyPI
./scripts/publish.sh

Configuration

The application stores session data in a JSON file located at ~/.tmagent/sessions.json. This file tracks active sessions and their working directories.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• tmate - The terminal multiplexer used for session management
• rich - For beautiful terminal formatting
• questionary - For interactive command-line prompts
• qrcode - For QR code generation