Metadata-Version: 2.4
Name: tmuxr
Version: 1.1.0
Summary: Declarative tmux session manager — config lives in your repo.
Author: DVamsee
License-Expression: MIT
Project-URL: Homepage, https://github.com/DVamsee/cliin
Project-URL: Repository, https://github.com/DVamsee/cliin
Project-URL: Issues, https://github.com/DVamsee/cliin/issues
Keywords: tmux,session,manager,terminal,declarative
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: libtmux>=0.25
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: pytest-mock>=3.0; extra == "test"
Dynamic: license-file

# tmuxr

Declarative tmux session manager. Config lives in your repo.

## Prerequisites

- **Python** >= 3.11
- **tmux** installed and available in PATH

```bash
# macOS
brew install tmux

# Ubuntu / Debian
sudo apt install tmux
```

## Install

```bash
pip install tmuxr
```

To install from source:

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

To install with test dependencies:

```bash
pip install -e ".[test]"
```

## Quick Start

### 1. Create a `tmuxfile.yml` in your project root

```yaml
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

```bash
tmuxr up
```

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

### 3. Other commands

```bash
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

```yaml
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

```yaml
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

```yaml
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](docs/ARCHITECTURE.md).

## Running Tests

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

## License

MIT
