mox

A CLI tool for creating and managing tmux sessions declaratively from YAML configuration files — with cssh-style multi-host broadcast built in.

Run mox and pick a session:

Or see everything at a glance with mox list:

Features

• Declarative YAML config — one window per host, full custom layouts, or anything between; project-local .mox.yml overrides; editor autocomplete via a published JSON Schema
• Cssh-style broadcast — sync: true for synchronized typing; tiled layouts; sudo -i once for every pane
• Ad-hoc sessions — mox new @cluster or mox new host1 host2 without touching config; -x excludes hosts; --save keeps the definition
• Session picker — bare mox opens a fuzzy-filterable list with a live preview pane
• Config without YAML — mox add walks a short wizard; mox import captures a running session — structure, pane geometry, and its SSH connections
• Broadcast safety — an ended connection holds its pane instead of dropping to a local shell; optional retry
• Lifecycle hooks — on_start/on_stop run locally around a session; pre seeds every pane
• Recents — mox recent remembers what you used; mox last is cd - for sessions
• Dry-run — --print shows the exact tmux commands without running them
• Honest defaults — single binary, no daemon, strict config validation; the only state is a small recents history

Install

# Go
go install github.com/bthall/mox/cmd/mox@latest

# From source (also installs shell completion)
git clone https://github.com/bthall/mox.git && cd mox && make install

# Arch Linux (source build)
cd packaging/aur && makepkg -si

Pre-built archives for linux/macOS × amd64/arm64 are attached to each release with checksums.txt.

Quick start

mox init                        # scaffold a config at ~/.config/mox/config.yml
mox add                         # interactively add a session to it
mox edit                        # or open it in $EDITOR, validated on save
mox -a example                  # build + attach to the "example" session
mox                             # or pick a session interactively
mox new @webfarm                # ad-hoc broadcast session on a cluster
mox kill example                # destroy a running session

Documentation

• Configuration — the YAML schema: sessions, windows, layouts, connect templates, hooks, holding/retry, validation rules
• Commands — every command and flag, the picker, cluster expansion, dry-run, shell completion
• Recipes — copy-paste workflows, from quick local sessions to clusterssh migration

Contributing

make test, make lint, and make integration cover the local loop; CI runs all three plus govulncheck on every push. See CONTRIBUTING.md and SECURITY.md.

License

MIT