.TH SMUX-CONFIG 5
.SH NAME
smux-config \- configuration file format for smux
.SH SYNOPSIS
.B ~/.config/smux/config.toml
.SH DESCRIPTION
\fBsmux\fR reads a main TOML configuration file plus optional project files.
By default the file is loaded from \fB~/.config/smux/config.toml\fR.
If \fBXDG_CONFIG_HOME\fR is set, \fBsmux\fR uses
\fB$XDG_CONFIG_HOME/smux/config.toml\fR.
.PP
Project definitions live in \fB~/.config/smux/projects/*.toml\fR or
\fB$XDG_CONFIG_HOME/smux/projects/*.toml\fR.
.SH OVERVIEW
The main configuration has two top-level sections:
.IP \(bu 2
\fB[settings]\fR
.IP \(bu 2
\fB[templates.<name>]\fR
.SH SETTINGS
.SS [settings]
.nf
[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"
save_project = "ctrl-y"
[settings.picker.preview]
# sessions = "tmux capture-pane -p -t \"$SMUX_PREVIEW_SESSION\""
# folders = "eza --tree --level=2 --color=always --icons=always \"$SMUX_PREVIEW_PATH\""
# projects = "bat --style=plain --color=always --language=toml \"$SMUX_PREVIEW_FILE\""
[settings.folder_search]
# roots = ["~"]
# max_depth = 3
# include_hidden = false
.fi
.PP
\fBdefault_template\fR sets the template used when no CLI override or matching
project template applies.
.PP
\fBicons\fR controls picker icons and accepts \fBauto\fR, \fBalways\fR, or
\fBnever\fR.
.PP
\fBsettings.icon_colors\fR sets ANSI-256 icon colors for sessions,
directories, templates, and projects.
.PP
\fBsettings.picker.bindings\fR customizes the main picker keybinds.
\fBreset\fR resets to the full list, \fBsessions\fR filters to tmux sessions,
\fBfolders\fR filters to folders, \fBprojects\fR filters to saved projects,
\fBdelete_session\fR deletes the selected session or project, and
\fBsave_project\fR saves the selected tmux session as a project.
.PP
Picker binding values are passed through as \fBfzf\fR key names. They must not
be empty and must be unique within the picker binding block.
.PP
\fBsettings.picker.preview\fR customizes the right-side picker preview commands.
\fBsessions\fR receives \fBSMUX_PREVIEW_SESSION\fR,
\fBfolders\fR receives \fBSMUX_PREVIEW_PATH\fR, and
\fBprojects\fR receives \fBSMUX_PREVIEW_FILE\fR.
When unset, \fBsmux\fR uses built-in defaults: tmux window and pane summaries for
sessions, \fBeza\fR or \fBls -la\fR for folders, and \fBbat\fR or
\fBsed -n '1,200p'\fR for project files.
.PP
\fBsettings.folder_search\fR adds bounded filesystem directory discovery to
\fBsmux select\fR in addition to zoxide. \fBroots\fR defaults to \fB["~"]\fR,
\fBmax_depth\fR defaults to \fB3\fR and must be at most \fB16\fR, and
\fBinclude_hidden\fR defaults to \fBfalse\fR. Folder search skips common
heavyweight directories such as \fBLibrary\fR, \fBnode_modules\fR, and
\fBtarget\fR.
.SH TEMPLATES
Templates define the tmux layout used when \fBsmux\fR creates a new session.
The recommended format uses TOML 1.1 inline tables for windows and panes.
.PP
\fBstartup_window\fR selects the window focused after creation.
\fBstartup_pane\fR selects a zero-based pane index within that startup window.
.PP
Template fields:
.IP \(bu 2
\fBroot\fR
.IP \(bu 2
\fBstartup_window\fR
.IP \(bu 2
\fBstartup_pane\fR
.IP \(bu 2
\fBwindows\fR (array of inline tables)
.PP
Window fields:
.IP \(bu 2
\fBname\fR
.IP \(bu 2
\fBcwd\fR
.IP \(bu 2
\fBpre_command\fR
.IP \(bu 2
\fBcommand\fR
.IP \(bu 2
\fBlayout\fR
.IP
tmux window layout name passed to \fBtmux select-layout\fR, for example
\fBtiled\fR, \fBmain-horizontal\fR, \fBmain-vertical\fR,
\fBeven-horizontal\fR, or \fBeven-vertical\fR
.IP
Applied after pane creation, so it may rearrange the final pane geometry.
.IP \(bu 2
\fBsynchronize\fR
.IP \(bu 2
\fBpanes\fR (array of inline tables)
.PP
Pane fields:
.IP \(bu 2
\fBlayout\fR
.IP
Controls how each new pane is created before any window-level tmux layout is applied.
.IP \(bu 2
\fBcwd\fR
.IP \(bu 2
\fBcommand\fR
.IP \(bu 2
\fBzoom\fR
.IP
Zooms that pane after the window has been created. At most one pane per window
may set \fBzoom = true\fR.
.PP
Rules:
.IP \(bu 2
A template must contain at least one window.
.IP \(bu 2
\fBstartup_window\fR must match an existing template window if set.
.IP \(bu 2
\fBstartup_pane\fR must be valid for the chosen startup window.
.IP \(bu 2
A window may define \fBcommand\fR or \fBpanes\fR or neither, but not both.
.IP \(bu 2
A \fBpanes\fR array cannot be empty.
.IP \(bu 2
\fBpre_command\fR runs before the pane or window command.
.IP \(bu 2
\fBwindow.layout\fR is passed through to tmux without additional validation.
.PP
Pane \fBlayout\fR values use the form \fB<position>\fR or
\fB<position> <size>\fR where position is one of \fBright\fR, \fBleft\fR,
\fBbottom\fR, or \fBtop\fR.
.PP
When both pane and window layout are set, pane layout controls split creation
and window layout is applied afterward with \fBtmux select-layout\fR.
That means window layout may rearrange the final pane geometry.
.SH PROJECTS
Projects are stored as individual files in \fB~/.config/smux/projects/\fR.
.nf
path = "~/code/myapp"
template = "rust"
session_name = "myapp"
.fi
.PP
The project name comes from the file name, for example
\fB~/.config/smux/projects/myapp.toml\fR.
.PP
Project files may either point at a reusable template or define their own
windows and startup behavior directly.
.nf
path = "~/code/myapp"
template = "rust"
session_name = "myapp"
.fi
.PP
Project fields:
.IP \(bu 2
\fBpath\fR (required)
.IP \(bu 2
\fBsession_name\fR (optional)
.IP \(bu 2
\fBtemplate\fR (optional)
.IP \(bu 2
\fBroot\fR (optional)
.IP \(bu 2
\fBstartup_window\fR (optional)
.IP \(bu 2
\fBstartup_pane\fR (optional)
.IP \(bu 2
\fBwindows\fR (optional; same structure as template windows)
.SH RESOLUTION ORDER
Template resolution order:
.IP "1." 4
\fB--template\fR
.IP "2." 4
matching project definition
.IP "3." 4
\fBsettings.default_template\fR
.IP "4." 4
built-in fallback template
.PP
Session name resolution order:
.IP "1." 4
\fB--session-name\fR
.IP "2." 4
matching project \fBsession_name\fR
.IP "3." 4
sanitized directory basename
.SH SEE ALSO
.BR smux (1)