🚀 tmux-compose

Define and manage complex tmux sessions with YAML configuration files

Like Docker Compose, but for tmux sessions 🐳 ➡️ 🖥️

---

✨ Features

• 📝 YAML Configuration - Define your tmux sessions declaratively
• 🪟 Multi-Window Support - Create multiple windows per session
• 🔀 Pane Management - Split windows into multiple panes with custom layouts
• ⚙️ tmux Config Aware - Respects your base-index and pane-base-index settings
• 🎯 Simple Commands - Docker Compose-like interface (up, down, ls)
• 🔄 Session Management - Start, stop, and list sessions effortlessly

🚀 Quick Start

Prerequisites

• tmux - Terminal multiplexer
• yq - YAML processor

Installation

Arch Linux

sudo pacman -S tmux yq

Ubuntu/Debian

sudo apt install tmux
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64
sudo chmod +x /usr/local/bin/yq

macOS

brew install tmux yq

Usage

1. Clone or download the script:

   curl -O https://raw.githubusercontent.com/your-username/tmux-compose/main/tmux-compose.sh
   chmod +x tmux-compose.sh

2. Create a tmux-compose.yml file:

   version: '1'
   
   sessions:
     - name: development
       windows:
         - name: editor
           command: nvim
         - name: server
           command: npm run dev

3. Start your sessions:

   ./tmux-compose.sh up

📖 Configuration Reference

Basic Structure

version: '1'

sessions:
  - name: session-name
    windows:
      - name: window-name
        command: command-to-run
        panes:
          - command: pane-command
            split: vertical|horizontal
        layout: layout-name

Complete Example

version: '1'

sessions:
  - name: web-development
    windows:
      - name: editor
        command: code .
      
      - name: frontend
        command: cd frontend
        panes:
          - command: npm run dev
          - command: npm run test:watch
            split: vertical
          - command: npm run lint:watch
            split: horizontal
        layout: main-vertical
      
      - name: backend
        command: cd backend
        panes:
          - command: python manage.py runserver
          - command: python manage.py shell
            split: horizontal
          - command: tail -f logs/app.log
            split: vertical
        layout: even-horizontal
      
      - name: database
        panes:
          - command: psql -d myapp
          - command: redis-cli
            split: horizontal

  - name: monitoring
    windows:
      - name: system
        command: htop
      - name: logs
        command: tail -f /var/log/syslog

Configuration Options

Option	Description	Values
version	Configuration version	'1'
name	Session/window name	String
command	Command to execute	Shell command
split	Pane split direction	vertical, horizontal
layout	tmux layout	even-horizontal, even-vertical, main-horizontal, main-vertical, tiled

🛠️ Commands

# Start all sessions defined in tmux-compose.yml
./tmux-compose.sh up

# Stop all sessions
./tmux-compose.sh down

# List running sessions
./tmux-compose.sh ls

# Use custom config file
./tmux-compose.sh -f my-config.yml up

# Show help
./tmux-compose.sh --help

🎯 Use Cases

Development Environment

Perfect for setting up consistent development environments with editors, servers, databases, and monitoring tools.

DevOps Workflows

Manage multiple services, logs, and monitoring dashboards in organized tmux sessions.

System Administration

Create dedicated sessions for different servers, services, or maintenance tasks.

🔧 Advanced Features

tmux Configuration Compatibility

The script automatically detects and respects your tmux configuration:

• base-index - Starting index for windows (usually 0 or 1)
• pane-base-index - Starting index for panes (usually 0 or 1)

Layout Options

tmux-compose supports all standard tmux layouts:

• even-horizontal - Panes arranged horizontally with equal width
• even-vertical - Panes arranged vertically with equal height
• main-horizontal - One main pane on top, others below
• main-vertical - One main pane on left, others on right
• tiled - Panes arranged in a grid

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Test your changes with various tmux configurations
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📝 License

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

🙏 Acknowledgments

• Inspired by Docker Compose
• Built for the amazing tmux terminal multiplexer
• Uses yq for YAML processing

---

⭐ Star this repo if you find it useful!

Made with ❤️ for the terminal enthusiasts