tmuxr 1.0.0

Declarative tmux session manager — config lives in your repo.

cliin

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

# Clone the repo
git clone <repo-url>
cd cliin

# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install cliin
pip install -e .

# Verify
cliin --version

To install with test dependencies:

pip install -e ".[test]"

Note: Always activate the virtual environment (source .venv/bin/activate) before using cliin.

Quick Start

1. Create a .cliin.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

cliin up

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

3. Other commands

cliin down        # kill the session
cliin status      # list running cliin sessions
cliin up -d       # start without attaching (detached mode)
cliin 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 cliin up from any subdirectory — cliin walks up the directory tree to find .cliin.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 .cliin.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 CLIIN_MANAGED=1 on the tmux session so cliin status only shows cliin-managed sessions

For more details, see docs/ARCHITECTURE.md.

Running Tests

source .venv/bin/activate
pip install -e ".[test]"
pytest tests/ -v

License

MIT