tmuxr

Declarative tmux session manager. Config lives in your repo.

Prerequisites

• Python >= 3.11
• tmux installed and available in PATH

# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux

Install

pip install tmuxr

To install from source:

git clone https://github.com/DVamsee/cliin.git
cd cliin
pip install -e .

To install with test dependencies:

pip install -e ".[test]"

Quick Start

1. Create a tmuxfile.yml in your project root

session: my-app

windows:
  - name: backend
    dir: ./backend
    cmd: npm run dev

  - name: frontend
    dir: ./frontend
    cmd: npm run dev

  - name: worker
    cmd: python worker.py

2. Start the session

tmuxr up

That's it. tmuxr creates a tmux session with three windows, each running its command in the right directory.

3. Other commands

tmuxr down        # kill the session
tmuxr status      # list running tmuxr sessions
tmuxr up -d       # start without attaching (detached mode)
tmuxr up -f custom.yml  # use a different config file

Config Reference

Top-level fields

Window fields

Path resolution

All paths (dir, env_file) are resolved relative to the config file's location, not cwd. You can run tmuxr up from any subdirectory — tmuxr walks up the directory tree to find tmuxfile.yml, just like git finds .git/.

Examples

Web app with auto-restart

session: webapp

windows:
  - name: server
    cmd: python manage.py runserver
    restart: on-failure

  - name: worker
    cmd: celery -A app worker
    restart: always

  - name: shell
    cmd: bash

Monorepo with env files

session: platform

env_file: .env.shared

windows:
  - name: api
    dir: ./services/api
    cmd: go run .
    env_file: ./services/api/.env
    restart: on-failure

  - name: web
    dir: ./apps/web
    cmd: npm run dev

  - name: db
    dir: ./infra
    pre_cmd: docker-compose up -d postgres
    cmd: pgcli -d myapp

Python project with virtualenv

session: ml-pipeline

windows:
  - name: train
    cmd: python train.py
    pre_cmd: source .venv/bin/activate
    restart: on-failure

  - name: tensorboard
    cmd: tensorboard --logdir runs/
    pre_cmd: source .venv/bin/activate

  - name: jupyter
    cmd: jupyter lab --port 8888
    pre_cmd: source .venv/bin/activate

How It Works

1. Config parsing — reads tmuxfile.yml, validates fields, resolves relative paths to absolute
2. Session creation — creates a tmux session via libtmux, one window per entry
3. Window setup — for each window: cd to dir, source env files (global then per-window), run pre_cmd, run cmd
4. Process watching — starts background threads for windows with restart policy. Polls every 3s; if a process exits (pane falls back to shell), re-runs the setup sequence
5. Session tagging — sets TMUXR_MANAGED=1 on the tmux session so tmuxr status only shows tmuxr-managed sessions

For more details, see docs/ARCHITECTURE.md.

Running Tests

pip install -e ".[test]"
pytest tests/ -v

License

MIT