nux

Global config

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

The global config file controls defaults, discovery, pickers, and session groups for all projects.

Location#

nux follows the XDG Base Directory Specification. The config file is located at:

$XDG_CONFIG_HOME/nux/config.yaml

On most systems this resolves to ~/.config/nux/config.yaml. If $XDG_CONFIG_HOME is set to a custom path, nux uses that instead.

You can override the config directory at runtime with --config-dir <path>. This also changes where nux looks for project configs (<path>/projects/).

If the config file does not exist, nux applies built-in defaults silently (no error).

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:

Monorepo Setup

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

In a monorepo you often want each tmux window to start in a different subdirectory while still belonging to one nux project. Use per-window root values: they are paths relative to the project root, so one config can place windows under apps/frontend, apps/backend, packages/shared, and so on.

Example: project “acme-mono”#

Assume the repo on disk is ~/code/acme-mono with sub-apps under apps/ and shared code under packages/. A single project config can set the session root to the monorepo root and give each window its own subdirectory.

stop

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

Usage#

nux stop <session> [session ...]

Description#

Stops one or more tmux sessions by name. You can pass multiple session arguments in a single invocation.

Session names accept glob patterns (for example web+ matches related session names) and group expansion with the @ prefix (for example @work expands to every session in that group).

stop-all#

nux stop-all

Kills every running tmux session. This is a blunt reset when you want no sessions left running. It is separate from nux stop (which requires at least one session argument).

Lifecycle Hooks

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

Project configs can define four hooks that run shell commands at well-defined points in the session lifecycle.

Hook	When it runs	Mechanism
`on_start`	After the session and first window are created, before remaining windows	`SendKeys` to the first pane
`on_stop`	When the session ends	tmux hook (`session-closed`)
`on_ready`	Once, at the end of the full session build	`SendKeys` to the first pane
`on_detach`	Each time a client detaches from the session	tmux hook (`client-detached`)

`on_start`#

Runs once after the session and its first window are created. Commands are sent as keystrokes to the first pane of the first window. Use it for one-time setup like starting background services.

Project config

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

Each project is defined in a YAML file under the nux config directory:

$XDG_CONFIG_HOME/nux/projects/<name>.yaml

On most systems this is ~/.config/nux/projects/<name>.yaml. The file name (without .yaml) becomes the project name on the CLI.

Session name normalization#

The tmux session name is derived from the project name with these transformations:

Dots (.), colons (:), and spaces are replaced with underscores (_)
Leading dashes are stripped
Consecutive underscores are collapsed to one
Trailing underscores are stripped

For example, a file named my.cool-project.yaml produces the session name my_cool-project.

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).

restart

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

Usage#

nux restart <target> [target ...]

Description#

Stops each matching session, then starts it again so changes in the project config are picked up. By default, nux attaches to the last restarted session.

Targets support glob patterns (+ matches any suffix, same as nux and nux stop), @group expansion from the global config, and multiple space-separated names.

Use the :window suffix to restart one or more windows (comma-separated) inside a session without tearing down the rest.

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).

Pattern Matching

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

Many nux commands accept a project pattern instead of an exact name. The special character + means “zero or more characters” and can appear anywhere in the pattern.

Where `+` can appear#

Suffix: web+ matches names starting with web (e.g. web-app, web-admin)
Prefix: +wiki matches names ending with wiki (e.g. dev-wiki, team-wiki)
Infix: +api+ matches any name containing api (e.g. my-api-server)
Multiple: w+a+ matches names starting with w that also contain a

Internally, each + is translated to .* and the pattern is anchored as ^...$, so it must match the full project name.

Session groups

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

Groups are named lists of project names in global config under the groups key. They let you start or stop several projects at once without typing each name.

Defining groups#

groups:
 work:
 - api
 - web
 - workers
 personal:
 - blog
 - dotfiles

Each entry is a project name - the basename of a file in ~/.config/nux/projects/ (without .yaml), or any name resolvable via project_dirs or zoxide.

Usage#

Start every session in a group:

show

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

Usage#

nux show <target> [target ...]

Description#

Prints the fully resolved config for one or more projects as YAML. The output reflects the state after interpolation ({{var}} substitution), environment expansion (${VAR}), and root resolution - exactly what nux would use to build the session.

Targets support glob patterns (+), @group expansion, and multiple space-separated names. Multiple projects are written as a YAML stream: one document per project, separated by a --- line.

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).

Default session

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

When a project has no config file under ~/.config/nux/projects/, nux builds a session from default_session in global config. This is why commands like nux blog can work with zero project file - the template provides the layout.

No default_session set#

If default_session is omitted from global config entirely, nux still creates a session - it just gets a single empty window with no commands. This is a bare tmux session rooted at the project directory.

list

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

Usage#

nux list

Alias: nux ls

Description#

Lists all projects that have a config file under ~/.config/nux/projects/, along with their current status.

Column	Meaning
NAME	Project name (derived from the config filename)
STATUS	`running` if a tmux session is active, `-` otherwise
WINDOWS	Number of windows in the running session (blank if not running)
UPTIME	How long the session has been running (blank if not running)
CONFIG	`project` (all listed entries come from config files)
ROOT	The `root` value from the project config, if set

Only projects with explicit config files appear here. Convention-based projects (discovered via project_dirs or zoxide) are not included unless they also have a config file.

Selective Windows

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

You can target individual windows with the :window suffix on the project name, optionally with multiple windows separated by commas. Window names match the name field under windows in your project config.

Syntax#

nux project:window
nux project:window1,window2,...
nux restart project:window
nux restart project:window1,window2,...

Starting a subset (root command)#

nux myapp:editor
nux myapp:editor,server

Creates the session with only the listed windows, in the order you list (not necessarily YAML order). Session-level options (env, on_start, on_ready, hooks) still apply; on_start and on_ready run against the first window in your list as the anchor.

config

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

Usage#

nux config

Description#

Opens the global nux config in $EDITOR. If the config file does not exist yet, a scaffold with commented examples is created first.

The generated scaffold contains all available settings with sensible defaults. Optional settings are commented out with examples so you can enable them as needed.

Behavior#

When no config exists:

The config directory and projects/ subdirectory are created.
A scaffold config.yaml is written with default values, commented examples, and a schema modeline for editor IntelliSense.
nux prints Created <path>.
If $EDITOR is set, the file is opened in your editor. Otherwise nux prints hint: set $EDITOR to open new configs automatically.

When a config already exists:

Environment variables

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

The env field in a project config sets session-scoped environment variables using tmux set-environment. Every pane in that session inherits them.

Syntax#

Values are strings. You can reference existing process environment variables with ${VAR} and use default fallbacks with ${VAR:-default}:

env:
 NODE_ENV: development
 PORT: "3000"
 DATABASE_URL: "${DATABASE_URL_DEV}"
 LOG_LEVEL: "${LOG_LEVEL:-info}"

Interpolation#

Environment variable values go through the same interpolation pipeline as other config fields:

Custom variables - {{var}} placeholders are resolved from the vars block
Environment expansion - ${VAR} references are expanded using Go’s os.ExpandEnv

This means you can combine both:

ps

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

Usage#

nux ps

Description#

Shows currently running tmux sessions in a table.

Column	Meaning
NAME	Session name
WINDOWS	Number of windows in the session
ATTACHED	`yes` if a client is attached, `no` otherwise
UPTIME	How long the session has been running (e.g. `5m`, `1h 32m`)

If no sessions are running, nux prints No running sessions.

This command shows all tmux sessions, not just those started by nux.

Example output#

NAME WINDOWS ATTACHED UPTIME
blog 2 yes 5m
api 3 no 1h 32m
docs 1 no 45m

Notes#

For the full project catalog (including projects without a running session), use nux list.
Uptime is rounded to the nearest minute.

Zoxide Integration

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

zoxide tracks directories you visit frequently. When zoxide integration is enabled, nux can resolve a project by name even when there is no matching config file, by running zoxide query <name> as a fallback.

Behavior#

If you have visited a directory before, nux my-obscure-project can succeed when that name resolves via zoxide - even without a config file at ~/.config/nux/projects/my-obscure-project.yaml.

When a project resolves through zoxide, no project config is loaded. The session is built using the default_session template (if configured) or as a bare session with a single window.

Custom variables

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

The vars field in project config defines named values you can reuse across the file.

`{{var}}` interpolation#

Use double-brace names in any string field - root, hooks, env values, and window or pane fields (including pane command when using the object pane form):

vars:
 app_name: myapp
 deploy_env: staging

root: ~/projects/{{app_name}}

env:
 APP_NAME: "{{app_name}}"
 DEPLOY_ENV: "{{deploy_env}}"

windows:
 - name: api
 panes:
 - ./bin/{{app_name}}-api

Resolution order#

Interpolation happens in this order:

Interactive Picker

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

When you run nux with no arguments from a directory that is not tied to a project, nux can open an interactive fuzzy finder instead of printing help.

What the picker shows#

The picker combines three sources into a single sorted list:

Configured projects (files in ~/.config/nux/projects/)
Directories under each project_dirs entry (top-level only, hidden directories excluded)
Running tmux sessions not covered by the above

Projects that have a config file are marked with a * suffix so you can tell at a glance which entries have custom configs and which use the default session template:

new

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

Usage#

nux new <name>

Description#

Creates a new project config file at ~/.config/nux/projects/<name>.yaml and opens it in $EDITOR if set.

The generated config includes a schema modeline for editor IntelliSense and a minimal template:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Drew-Daniels/nux/main/schemas/project.schema.json
windows:
 - name: editor

Edit this file to define your windows, panes, commands, and other project settings.

Behavior#

If a config for <name> already exists, nux exits with an error (it will not overwrite).
The config file is written to disk.
nux prints Created <path>.
If $EDITOR is set, nux opens the new file in your editor.
If $EDITOR is not set, nux prints hint: set $EDITOR to open new configs automatically.

Errors#

config already exists: <path> - a file with that name already exists. Use nux edit <name> to modify it, or nux delete <name> to remove it first.

Examples#

# Create and edit a new project config
nux new blog

# Create without opening an editor (when $EDITOR is unset)
unset EDITOR && nux new api

Post-save validation#

When the editor closes, nux re-loads and validates the config. Errors are printed as [error] and a clean config prints Config valid. If the YAML is unparseable, a syntax error warning is shown instead.

edit

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

Usage#

nux edit <name>

Description#

Opens the project config file for <name> in your $EDITOR. The file is located at ~/.config/nux/projects/<name>.yaml.

This is a convenience shortcut - equivalent to running $EDITOR ~/.config/nux/projects/<name>.yaml yourself.

Errors#

$EDITOR is not set - set the EDITOR environment variable in your shell profile (e.g. export EDITOR=nvim).
config not found: <path> - no config file exists for that project name. Use nux new <name> to create one first.

Examples#

# Edit an existing project config
nux edit blog

# Common EDITOR values
export EDITOR=nvim # Neovim
export EDITOR=vim # Vim
export EDITOR=code # VS Code
export EDITOR=nano # Nano

Post-save validation#

Editor IntelliSense

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

JSON Schemas ship in the nux repository for both config types:

schemas/global.schema.json - global config.yaml
schemas/project.schema.json - per-project YAML under projects/

Point your YAML language server at these schemas to get completion, validation, and hover docs in your editor.

The schemas include:

Required panes — windows without at least one pane are flagged inline.
Layout validation — named layouts (tiled, main-vertical, etc.) get autocomplete, and custom tmux layout strings are also accepted.
String-or-object shorthands — panes: [nvim] is recognized as valid.

nux config and nux new automatically include the appropriate schema modeline in generated files. For existing configs or manual setup, use one of the methods below.

Tool Sessions

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

Tool sessions are nux projects that exist mainly to launch a single utility (database TUI, log tailer, container dashboard, and so on). They are not special-cased in nux: they are normal project configs that often define one window and sometimes omit a meaningful repo layout.

Typical shape#

root can be omitted or set to any directory (home, a log path, a repo, or /tmp).
For a single command and one pane, use one window with a single panes entry.

Example configs#

Database client (single TUI)

delete

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

Usage#

nux delete <name> [name ...]

Alias: nux del

Description#

Deletes one or more project config files. By default, nux prompts for confirmation before each deletion.

This only removes config files at ~/.config/nux/projects/<name>.yaml. It does not delete project directories, source code, or stop any running sessions.

Supports glob patterns with + and group expansion with @.

Flags#

Flag	Meaning
`--force`	Skip confirmation prompts

Behavior#

Arguments are expanded (patterns and groups resolved to individual names).
For each target, nux checks that the config file exists.
Unless --force is set, nux prompts: Delete config for "<name>"? [y/N]
If confirmed, the file is deleted and nux prints Deleted config for "<name>".
If declined, nux prints Cancelled. and moves on to the next target.

Errors#

config not found: <path> - no config file exists for that project name.

Examples#

# Delete with confirmation prompt
nux delete old-project

# Delete without prompting
nux delete old-project --force

# Delete multiple projects
nux delete blog api docs

# Delete all projects matching a pattern
nux del web+ --force

# Delete all projects in a group
nux del @deprecated --force

Notes#

If a session for the deleted project is still running, it continues until stopped. Use nux stop <name> first if you want to tear down the session.
After deletion, the project can still start via convention (directory under any configured project_dirs path) or zoxide, but without any custom config.

reset

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

Usage#

nux reset

Description#

Removes the global nux config file so you can start fresh. Use --projects to also remove all project config files.

Before anything is deleted, a summary of what will be removed and what will be kept is printed.

Flags#

Flag	Meaning
`--force`	Skip the confirmation prompt
`--projects`	Also remove all project configs

Behavior#

nux checks that config.yaml exists in the config directory.
A preview of what will be removed and what will be kept is printed.
Unless --force is set, nux prompts for confirmation.
The global config file is deleted.
If --projects is set, the projects/ directory and all its contents are also deleted.

Running tmux sessions are not affected by this command.

validate

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

Usage#

nux validate [name ...]

Description#

Validates project configuration files and reports errors. Each config is printed with [ok] or [error].

With no arguments: validates all project configs under ~/.config/nux/projects/.
With one or more targets: validates each expanded project. Targets support glob patterns (+), @group expansion, and multiple space-separated names (same rules as nux / nux stop).

What gets checked#

Every project must have at least one window with at least one pane.
Every window must have a name.
Every window must have at least one pane.
layout values must be a recognized tmux layout name or a valid custom layout string.

Example output#

 [ok] blog
 [ok] api
 [error] workers: at least one window is required

If any config has errors, nux exits with a non-zero status.

doctor

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

Usage#

nux doctor

Description#

Runs a diagnostic suite for your nux and tmux environment. Each check is reported with [ok], [warn], [fail], or [missing].

Checks performed, in order:

nux version - prints the running version, OS, and architecture
tmux binary - verifies tmux is on PATH and prints its version
Global config - confirms the global config loaded successfully
Zoxide binary - checked only when zoxide: true in global config
Picker binary - checked only when a picker is configured (fzf, gum)
Config directory - verifies ~/.config/nux/projects/ exists
Projects directory - verifies each configured project_dirs path exists
Project configs - validates every project YAML file

If any check fails, doctor exits with a non-zero status and prints “some checks failed.”

Troubleshooting

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

Common issues and how to resolve them.

“nux: unknown command” or “command not found”#

The nux binary is not on your PATH. Verify the install:

which nux
nux version

If you installed via go install, make sure $(go env GOPATH)/bin is in your PATH. If you installed via Homebrew, run brew link nux.

“cannot start session from inside tmux”#

nux refuses to start new sessions from inside an existing tmux session to prevent nested session confusion. Options:

completions

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

Usage#

nux completions <bash|zsh|fish>

Description#

Prints a shell completion script to standard output for the given shell. Redirect the output to the location your shell loads for completions.

Install examples#

bash

nux completions bash > /etc/bash_completion.d/nux

zsh

nux completions zsh > "${fpath[1]}/_nux"

fish

nux completions fish > ~/.config/fish/completions/nux.fish

Notes#

If you install nux via Homebrew or Nix, completions are often installed automatically; you may not need the steps above.
You may need elevated permissions for system-wide paths (for example /etc/bash_completion.d).

version

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

Usage#

nux version

Description#

Prints build metadata: version, git commit, and build date.

Example output#

nux 0.5.0
 commit: a1b2c3d
 built: 2026-04-01T12:00:00Z

When running a development build (via go install or go build without ldflags), the output shows placeholder values:

nux dev
 commit: none
 built: unknown

Changelog#

See the GitHub releases page for release notes and changelogs.

Notes#

Useful when reporting bugs or verifying that your PATH points to the expected install.
Release builds embed version info via -ldflags at compile time.

GitHub repository setup

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

This page documents maintainer-facing GitHub settings for nux. Most files live in the repo (templates, Dependabot, workflows); a few settings are only in the GitHub UI or API.

Files in the repo#

Item	Location
Security policy	SECURITY.md
Code of Conduct	CODE_OF_CONDUCT.md
Support / where to ask	SUPPORT.md
Issue forms	.github/ISSUE_TEMPLATE/
PR template	.github/PULL_REQUEST_TEMPLATE.md
Dependabot	.github/dependabot.yml
Sponsor button	.github/FUNDING.yml
Stale issues (optional)	.github/workflows/stale.yml

Settings applied via GitHub API#

These can be configured with gh (see project history). To reproduce or audit:

nux

Global config

Location#

Installation

Homebrew#

Go install#

Nix#

Monorepo Setup

Example: project “acme-mono”#

stop

Usage#

Description#

stop-all#

Lifecycle Hooks

on_start#

Project config

Session name normalization#

Quickstart

Global config#

restart

Usage#

Description#

Migrating from tmuxinator

Templating and variables#

Project root#

Pattern Matching

Where + can appear#

Session groups

Defining groups#

Usage#

show

Usage#

Description#

Comparison with alternatives

Config-driven session managers#

Default session

No default_session set#

list

Usage#

Description#

Selective Windows

Syntax#

Starting a subset (root command)#

config

Usage#

Description#

Behavior#

Environment variables

Syntax#

Interpolation#

ps

Usage#

Description#

Example output#

Notes#

Zoxide Integration

Behavior#

Custom variables

{{var}} interpolation#

Resolution order#

Interactive Picker

What the picker shows#

new

Usage#

Description#

Behavior#

Errors#

Examples#

Post-save validation#

edit

Usage#

Description#

Errors#

Examples#

Post-save validation#

Editor IntelliSense

Tool Sessions

Typical shape#

Example configs#

delete

`on_start`#

Where `+` can appear#

`{{var}}` interpolation#