SMUX-CONFIG(5)

NAME
smux-config - configuration file format for smux

SYNOPSIS
~/.config/smux/config.toml

DESCRIPTION
smux reads a main TOML configuration file plus optional project files. By default the file is loaded from ~/.config/smux/config.toml. If XDG_CONFIG_HOME is set, smux uses $XDG_CONFIG_HOME/smux/config.toml.

Project definitions live in ~/.config/smux/projects/*.toml or $XDG_CONFIG_HOME/smux/projects/*.toml.

OVERVIEW
The main configuration has two top-level sections:

•   [settings]

•   [templates.<name>]

SETTINGS

  [settings]
[settings]
default_template = "default"
icons = "auto"
[settings.icon_colors]
session = 75
directory = 108
template = 179
project = 81
[settings.picker.bindings]
reset = "ctrl-c"
sessions = "ctrl-s"
folders = "ctrl-f"
projects = "ctrl-p"
delete_session = "ctrl-x"

default_template sets the template used when no CLI override or matching project template applies.

icons controls picker icons and accepts auto, always, or never.

settings.icon_colors sets ANSI-256 icon colors for sessions, directories, templates, and projects.

settings.picker.bindings customizes the main picker keybinds. reset resets to the full list, sessions filters to tmux sessions, folders filters to folders, projects filters to saved projects, and delete_session closes the selected non-current tmux session.

Picker binding values are passed through as fzf key names. They must not be empty and must be unique within the picker binding block.

TEMPLATES
Templates define the tmux layout used when smux creates a new session. The recommended format uses TOML 1.1 inline tables for windows and panes.

startup_window selects the window focused after creation. startup_pane selects a zero-based pane index within that startup window.

Template fields:

•   root

•   startup_window

•   startup_pane

•   windows (array of inline tables)

Window fields:

•   name

•   cwd

•   pre_command

•   command

•   layout

    tmux window layout name passed to tmux select-layout, for example tiled, main-horizontal, main-vertical, even-horizontal, or even-vertical

    Applied after pane creation, so it may rearrange the final pane geometry.

•   synchronize

•   panes (array of inline tables)

Pane fields:

•   layout

    Controls how each new pane is created before any window-level tmux layout is applied.

•   cwd

•   command

•   zoom

    Zooms that pane after the window has been created. At most one pane per window may set zoom = true.

Rules:

•   A template must contain at least one window.

•   startup_window must match an existing template window if set.

•   startup_pane must be valid for the chosen startup window.

•   A window may define command or panes or neither, but not both.

•   A panes array cannot be empty.

•   pre_command runs before the pane or window command.

•   window.layout is passed through to tmux without additional validation.

Pane layout values use the form <position> or <position> <size> where position is one of right, left, bottom, or top.

When both pane and window layout are set, pane layout controls split creation and window layout is applied afterward with tmux select-layout. That means window layout may rearrange the final pane geometry.

PROJECTS
Projects are stored as individual files in ~/.config/smux/projects/.
path = "~/code/myapp"
template = "rust"
session_name = "myapp"

The project name comes from the file name, for example ~/.config/smux/projects/myapp.toml.

Project files may either point at a reusable template or define their own windows and startup behavior directly.
path = "~/code/myapp"
template = "rust"
session_name = "myapp"

Project fields:

•   path (required)

•   session_name (optional)

•   template (optional)

•   root (optional)

•   startup_window (optional)

•   startup_pane (optional)

•   windows (optional; same structure as template windows)

RESOLUTION ORDER
Template resolution order:

1.  --template

2.  matching project definition

3.  settings.default_template

4.  built-in fallback template

Session name resolution order:

1.  --session-name

2.  matching project session_name

3.  sanitized directory basename

SEE ALSO
smux(1)