SMUX-CONFIG(5)

💖 SMUX-CONFIG(5) — the smux-config page, but make it make sense 💖

Okay bestie, welcome to the File Formats Manual page for SMUX-CONFIG(5) — aka smux-config. It's giving config blueprint, and we're keeping every lil' fact exactly where it belongs. No cap. 🫶

✨ NAME ✨

smux-config — configuration file format for smux. That's the whole name vibe, and it slays. 🎀

🦋 SYNOPSIS 🦋

~/.config/smux/config.toml

Yep, that's the path, periodt. 💅

🌸 DESCRIPTION 🌸

Okay so 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.

Template definitions live in ~/.config/smux/templates/*.toml and project definitions in ~/.config/smux/projects/*.toml (or under $XDG_CONFIG_HOME/smux/), one file per definition. Obsessed with the one-file-per-definition organization tbh. ✨

💅 OVERVIEW 💅

config.toml holds a single [settings] section. Templates and projects each live in their own directory as one file per definition, where the file name is the template or project name. Iconic separation, fr fr. 🎀

👑 SETTINGS 👑

🎀 [settings] 🎀

Here's the code block, exactly as the manual gives it — no edits, no "fixing" the commented preview lines, because we respect the receipts. 🧾

[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"
windows = "ctrl-w"
folders = "ctrl-f"
projects = "ctrl-p"
repos = "ctrl-g"
delete_session = "ctrl-x"
save_project = "alt-s"
rename_session = "ctrl-r"
edit_project = "ctrl-e"
choose_template = "ctrl-t"
toggle_hints = "?"

[settings.picker.preview]
# sessions = "tmux capture-pane -p -t
# folders = "eza --tree --level=2 --color=always --icons=always
# projects = "bat --style=plain --color=always --language=toml

[settings.folder_search]
# roots = ["~"]
# max_depth = 3
# include_hidden = false

[settings.clone]
# root = "~/Development"
# owners = ["my-org"]

• default_template — sets the template used when no CLI override or matching project template applies. Lowkey the fallback queen. 👑
• icons — controls picker icons and accepts auto, always, or never. Pick your icon energy. ✨
• settings.icon_colors — sets ANSI-256 icon colors for sessions, directories, templates, and projects. Color moment, no cap. 🌈
• settings.picker.bindings — customizes the main picker keybinds. Here's every single one, bestie:
  • reset — resets to the full list.
  • sessions — filters to tmux sessions.
  • windows — switches to individual tmux windows across all sessions (hidden from the default list; Enter jumps straight to the selected window).
  • folders — filters to folders.
  • projects — filters to saved projects.
  • repos — switches to your GitHub repositories (hidden from the default list and fetched on demand via gh; Enter clones the selection into settings.clone root, or just connects when a checkout already exists).
  • delete_session — deletes the selected session or project.
  • save_project — saves the selected tmux session as a project.
  • rename_session — renames the selected tmux session.
  • edit_project — opens the selected project file in the editor.
  • choose_template — opens the selected folder and prompts for its template by hand (overriding auto-detection for that folder).
  • toggle_hints — shows or hides the keyboard-shortcut hint bar.
• settings.picker.show_hints — boolean, default true; sets whether the hint bar is shown initially. It can always be toggled at runtime with toggle_hints. 🫶

🚨 Picker binding values are passed through as fzf key names. They must not be empty and must be unique within the picker binding block. That's a hard vibe check, not a suggestion.

• settings.picker.preview — customizes the right-side picker preview commands. sessions receives SMUX_PREVIEW_SESSION, folders receives SMUX_PREVIEW_PATH, and projects receives SMUX_PREVIEW_FILE. When unset, smux uses built-in defaults: tmux window and pane summaries for sessions, eza or ls -la for folders, and bat or sed -n '1,200p' for project files. 💅
• settings.folder_search — adds bounded filesystem directory discovery to smux select in addition to zoxide. roots defaults to ["~"], max_depth defaults to 3 and must be at most 16, and include_hidden defaults to false. Folder search skips common heavyweight directories such as Library, node_modules, and target. Bounded and bougie. 🦋
• settings.clone — configures smux clone and the picker's repository list. root is the directory new checkouts land in when no target directory is given with --dir (unset means the current working directory). owners lists extra GitHub owners (users or orgs) whose repositories appear alongside your own — in the repository browser that opens when smux clone runs without a URL, and in the picker's repos filter (both require the gh CLI). Clone era, activated. 🔥

🧚 TEMPLATES 🧚

Each template is a file in ~/.config/smux/templates/, one template per file, where the file name (without .toml) is the template name. A template defines the tmux layout used when smux creates a new session. The recommended format uses TOML 1.1 inline tables for windows and panes. So cute, so structured. 🎀

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

Template fields:

• match — array of marker patterns that auto-detect this template; exact filenames or simple */? globs, for example nuxt.config.*.
• match_dependencies — array of package.json dependency names that also auto-detect this template, for example react.
• priority — integer, default 0; higher wins when several templates match, letting a meta-framework beat its base.
• root
• startup_window
• startup_pane
• env — table of environment variables set on the session via tmux new-session -e; needs tmux >= 3.2.
• on_create — shell command run once in the session root before the session is created; a failing command aborts the connect.
• 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. Double layout moment, but that's the rule. 🫶

🍓 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. And yes, here's that same lil' snippet again, because the original page serves it twice — receipts kept, no cap. 🧾

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.
• env — optional; merged over the template's env, project entries win.
• on_create — optional; overrides the template's on_create.

🔥 RESOLUTION ORDER 🔥

Template resolution order:

1. --template
2. matching project definition
3. settings.default_template
4. auto-detected template: a template whose match files or match_dependencies are present in the directory; when several match, highest priority wins, then the most specific (longest) pattern, then the alphabetically first name
5. built-in fallback template

When opening a folder from the picker, if none of the above resolve a template and two or more templates are defined, smux prompts you to choose one instead of using the built-in fallback. Picker said choose your fighter. 💅

Session name resolution order:

1. --session-name
2. matching project session_name
3. sanitized directory basename

🌈 SEE ALSO 🌈

• smux(1) — go read the big sibling page, bestie. 🫶

---

Okay bestie, that's the whole SMUX-CONFIG(5) page from the File Formats Manual. This copy didn't give us a date/version line, so we're not inventing one — just preserving the facts, the flags, the defaults, and the vibe. smux-config out. 💖✨💅