Getting Started on nux

Installation

Mon, 01 Jan 0001 00:00:00 +0000

Install nux using one of the methods below. You need tmux 3.0 or newer on your PATH before using nux.

Homebrew#

brew install Drew-Daniels/tap/nux

To upgrade later:

brew upgrade nux

Go install#

Requires Go 1.26 or newer:

go install github.com/Drew-Daniels/nux@latest

Ensure $(go env GOPATH)/bin is on your PATH.

To upgrade, run the same command again - it always installs the latest version.

Nix#

Install into your profile:

nix profile install github:Drew-Daniels/nux

Try without installing:

Quickstart

Mon, 01 Jan 0001 00:00:00 +0000

This walkthrough assumes nux is installed and tmux 3.0+ is available. See Installation if you have not set that up yet.

Global config#

Create ~/.config/nux/config.yaml to configure defaults:

project_dirs: ~/projects
default_shell: /bin/zsh
pane_init:
 - eval "$(direnv hook zsh)"
default_session:
 windows:
 - name: main
 panes:
 - dev

project_dirs - base directory or list of directories for convention-based project discovery; a string or YAML list of strings (default: ~/projects). When multiple paths are set, nux scans all of them; the first entry is the base for relative root in project configs.
default_shell - shell used for new panes (optional, tmux default if omitted)
pane_init - commands run in each pane before pane-specific commands (optional)
default_session - template for projects without a config file; an object with a windows array (same shape as project config), for example one window with a single pane command

If you skip the global config entirely, nux uses built-in defaults (project_dirs: ~/projects, picker: fzf).

Migrating from tmuxinator

Mon, 01 Jan 0001 00:00:00 +0000

nux replaces tmuxinator-style YAML with its own schema and CLI. This page maps concepts and highlights what does not carry over one-to-one.

Templating and variables#

tmuxinator uses ERB (<%= ... %>). nux does not embed Ruby.

Custom template variables use {{var}} syntax.
Environment variables use ${VAR} syntax (shell-style).

Project root#

In tmuxinator, root is often explicit. In nux, if you omit root, it defaults to <first_project_dirs>/<project_name>: the first project_dirs entry when global config lists multiple paths, otherwise that single path (from global config and the project name).

Comparison with alternatives

Mon, 01 Jan 0001 00:00:00 +0000

Several tools manage tmux sessions. This page compares nux with the most popular alternatives so you can decide which fits your workflow.

All of these tools are good. They solve overlapping problems - starting, switching, and managing tmux sessions - and if one already works for you, there may be no reason to switch. This page focuses on where they differ.

Config-driven session managers#

These tools build tmux sessions from declarative config files (YAML/JSON).