tmux-manager

A lightweight Python tool to manage long-running services using tmux sessions. Perfect for developers who need to manage multiple development servers, background tasks, or any persistent processes.

Features

• 🚀 Easy Service Management: Add, remove, edit, and list services with simple commands
• 🔄 Automatic Virtual Environment Detection: Automatically activates Python virtual environments (.venv or venv) if present in the project directory
• 📁 Persistent Configuration: Service definitions are saved and can be easily restarted after system reboots using start-all
• 🎯 Session Status Tracking: See which services are running or stopped at a glance
• 🛠️ Simple CLI Interface: Intuitive command-line interface for all operations
• ⚡ Complex Commands: Support for chained commands using &&, ||, and other shell operators

Requirements

• Python 3.6+
• tmux (install via your package manager)
  • Ubuntu/Debian: sudo apt install tmux
  • macOS: brew install tmux
  • Fedora: sudo dnf install tmux

Installation

Quick Install (Recommended)

Linux/macOS

1. Clone the repository and run the installer:

   git clone https://github.com/xozxro/tmux-manager.git
   cd tmux-manager
   ./install.sh

2. Or download directly:

   curl -o ~/bin/tmux_manager https://raw.githubusercontent.com/xozxro/tmux-manager/main/tmux_manager.py
   chmod +x ~/bin/tmux_manager

3. Ensure ~/bin is in your PATH:

   echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc
   source ~/.bashrc  # or ~/.zshrc

Windows (PowerShell)

1. Clone and run the installer:

   git clone https://github.com/xozxro/tmux-manager.git
   cd tmux-manager
   .\install.ps1

Note: Windows users need either WSL with tmux installed or a Windows tmux port.

Alternative Installation Methods

Method 1: Clone and Link

git clone https://github.com/xozxro/tmux-manager.git
cd tmux-manager
chmod +x tmux_manager.py
ln -s $(pwd)/tmux_manager.py ~/bin/tmux_manager

Method 2: System-wide Installation

sudo curl -o /usr/local/bin/tmux_manager https://raw.githubusercontent.com/xozxro/tmux-manager/main/tmux_manager.py
sudo chmod +x /usr/local/bin/tmux_manager

Usage

Adding a Service

Add a new service by specifying a name, working directory, and command:

tmux_manager add myapp ~/projects/myapp "npm run dev"

This will:

• Create a new tmux session named "myapp"
• Change to the specified directory
• Activate .venv or venv if it exists in that directory (Python projects)
• Run the specified command

Listing Services

View all configured services and their status:

tmux_manager list

Output example:

myapp: [running] cwd=/home/user/projects/myapp cmd='npm run dev'
api: [stopped] cwd=/home/user/projects/api cmd='python app.py'
worker: [running] cwd=/home/user/projects/worker cmd='celery worker'

Removing a Service

Remove a service and kill its tmux session:

tmux_manager remove myapp

Editing a Service

Update a service's working directory or command:

# Update command
tmux_manager edit myapp --command "npm run prod"

# Update working directory
tmux_manager edit myapp --path ~/projects/myapp-v2

# Update both
tmux_manager edit myapp --path ~/projects/myapp-v2 --command "npm run prod"

Starting All Services

Start all configured services at once (useful after a reboot):

tmux_manager start-all

Real-World Examples

Node.js/JavaScript Projects

# Production build with auto-restart on changes
tmux_manager add nextjs-app ~/projects/my-nextjs-app "npm run build && npm run start"

# Development server with hot reload
tmux_manager add react-dev ~/projects/my-react-app "npm install && npm run dev"

# Run tests in watch mode
tmux_manager add jest-watch ~/projects/my-app "npm test -- --watch"

# Multiple services for microservices
tmux_manager add api-gateway ~/projects/api-gateway "npm run build:watch & npm run start:dev"

Python Projects (with automatic venv activation)

# Django development server (will auto-activate .venv or venv)
tmux_manager add django-app ~/projects/django-blog "python manage.py runserver"

# FastAPI with auto-reload
tmux_manager add fastapi ~/projects/my-api "uvicorn main:app --reload --host 0.0.0.0"

# Celery worker with beat scheduler
tmux_manager add celery ~/projects/django-blog "celery -A myproject worker --beat --loglevel=info"

# Jupyter notebook server
tmux_manager add jupyter ~/projects/data-science "jupyter lab --no-browser --port=8888"

Database and Infrastructure Services

# PostgreSQL with custom data directory
tmux_manager add postgres ~ "postgres -D /usr/local/var/postgres"

# Redis with custom config
tmux_manager add redis ~ "redis-server /usr/local/etc/redis.conf"

# MongoDB replica set
tmux_manager add mongo ~/data "mongod --replSet rs0 --port 27017 --dbpath ./db1"

# Elasticsearch
tmux_manager add elastic ~ "elasticsearch -E path.data=/var/lib/elasticsearch"

DevOps and Monitoring

# Watch for file changes and rebuild
tmux_manager add auto-build ~/projects/my-app "nodemon --exec 'npm run build' --watch src"

# Continuous log monitoring
tmux_manager add logs ~ "tail -f /var/log/nginx/access.log | grep -v 'health-check'"

# Local development proxy
tmux_manager add proxy ~ "caddy reverse-proxy --from localhost:3000 --to localhost:8080"

# Docker compose services
tmux_manager add docker-services ~/projects/my-app "docker-compose up"

Complex Multi-Command Examples

# Install dependencies, build, and start
tmux_manager add fullstack ~/projects/app "npm install && npm run build && npm run start"

# Run migrations before starting server
tmux_manager add django-prod ~/projects/django "python manage.py migrate && gunicorn myapp.wsgi:application"

# Start multiple processes with error handling
tmux_manager add services ~/projects "npm run db:start && npm run cache:start && npm run app:start || echo 'Service failed to start'"

# Development with automatic restart on failure
tmux_manager add dev-server ~/projects/api "while true; do npm run dev || sleep 5; done"

Accessing Running Services

To attach to a running service's tmux session:

tmux attach -t myapp

To detach from a tmux session, press Ctrl+B then D.

Configuration

Services are stored in ~/.config/tmux_services/services.json. You can manually edit this file if needed:

{
  "myapp": {
    "path": "~/projects/myapp",
    "command": "npm run dev"
  },
  "api": {
    "path": "~/projects/api",
    "command": "python app.py"
  }
}

Tips and Tricks

1. Auto-start services on boot: Since tmux sessions don't persist across reboots, you can automatically restart all services on boot using one of these methods:

   Option A - Shell RC file (simple but runs on every terminal):

   echo 'tmux_manager start-all 2>/dev/null' >> ~/.bashrc  # or ~/.zshrc

   Option B - Systemd user service (recommended for Linux):

   Use the provided setup script:

   ./examples/setup-autostart.sh

   Or manually create ~/.config/systemd/user/tmux-manager.service:

   [Unit]
   Description=Start tmux-manager services
   After=network.target
   
   [Service]
   Type=oneshot
   ExecStart=/home/YOUR_USER/bin/tmux_manager start-all
   RemainAfterExit=yes
   
   [Install]
   WantedBy=default.target

   Then enable it:

   systemctl --user daemon-reload
   systemctl --user enable tmux-manager.service

   Option C - Cron job:

   crontab -e
   # Add this line:
   @reboot /home/YOUR_USER/bin/tmux_manager start-all

2. Quick session switching: Use tmux ls to list all sessions and tmux attach -t <name> to attach.

3. Kill all tmux sessions: tmux kill-server (use with caution!)

4. View logs: Attach to a service's session to see its output: tmux attach -t myapp

5. Python Virtual Environments: The tool automatically detects and activates .venv or venv directories in your project folder.

6. Session Management: Use Ctrl+B then D to detach from a session without stopping it.

7. Window Splitting: Inside a tmux session, use Ctrl+B then % for vertical split or " for horizontal split.

Troubleshooting

Service won't start

• Check if a tmux session with the same name already exists: tmux ls
• Verify the working directory exists
• Ensure the command is valid

Can't find tmux_manager command

• Ensure ~/bin is in your PATH: echo $PATH
• Check file permissions: ls -la ~/bin/tmux_manager

Virtual environment not activating

• Ensure .venv or venv directory exists in the service's working directory
• Check that the virtual environment is properly created with python -m venv .venv or python -m venv venv
• Verify the activate script exists at .venv/bin/activate or venv/bin/activate

FAQ

Do tmux sessions persist after reboot?

No, tmux sessions are cleared when the system reboots. However, tmux-manager saves your service configurations, so you can easily restart all services with:

tmux_manager start-all

To automatically start services on boot, see the "Auto-start services on boot" section in Tips and Tricks.

Can I use tmux-manager with existing tmux sessions?

Yes! tmux-manager only manages sessions it creates. Your existing tmux sessions won't be affected. If you try to add a service with a name that already exists as a tmux session, it will skip creation and notify you.

What happens if a service crashes?

The service will stop, but its configuration remains saved. You can restart it by running:

tmux_manager start-all  # restarts all stopped services

For automatic restart on failure, wrap your command in a loop:

tmux_manager add my-service ~/project "while true; do npm start || sleep 5; done"

Can I run multiple instances of the same service?

Yes, just use different names:

tmux_manager add web-1 ~/project "npm start -- --port 3001"
tmux_manager add web-2 ~/project "npm start -- --port 3002"

Contributing

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

License

This project is released into the public domain. Use it however you like!

Author

Created with ❤️ for developers who juggle multiple services daily.