tmuxr 1.1.1

Declarative tmux session manager — config lives in your repo.

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

Field	Type	Default	Description
session	string	required	tmux session name
env_file	string	null	Global .env file, sourced in every window
windows	list	required	List of window definitions

Window fields

Field	Type	Default	Description
name	string	required	Window name in tmux
cmd	string	required	Command to run
dir	string	.	Working directory (relative to config file)
restart	string	never	never / on-failure / always
env_file	string	null	Per-window .env file
pre_cmd	string	null	Command to run before main cmd

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