smux-cli 0.1.4

Small Rust CLI for tmux session selection and creation
Documentation

CI Release License: MIT

smux is a tmux session manager with fzf-powered session creation and switching.

Install • Quick Start • Common Workflows • Projects vs Templates • Config • Commands

Highlights:

  • quickly switch between existing tmux sessions
  • tmux session from directory - pick a recent directory and create or reuse a tmux session for it
  • tmux session from project - launch a saved project with a defined properties (path, name, windows, panes, layout, commands...)
  • apply reusable tmux templates with windows, panes, layouts, and startup commands

It works both inside and outside tmux. Inside tmux, it fits naturally in a popup. Outside tmux, it uses the current terminal.

Install

With Homebrew:

brew install smux

With Nix:

nix profile install nixpkgs#smux

With Cargo:

cargo install smux-cli

The published crates.io package is smux-cli, but the installed command is still smux.

Runtime dependencies:

  • required: tmux, fzf
  • optional but recommended: zoxide

If zoxide is unavailable, smux select still works with tmux sessions and saved projects.

Quick Start

Create a starter config:

smux init

Main config path, following the default XDG config location:

~/.config/smux/config.toml

Project definitions live alongside it:

~/.config/smux/projects/*.toml

Then start using it:

smux select

For normal day-to-day use, wire it into tmux and zsh:

Recommended tmux settings:

set -g detach-on-destroy off # keeps tmux running when you close a session
bind-key t display-popup -w 70% -h 70% -E "smux select"
bind-key T display-popup -w 70% -h 70% -E "smux select --choose-template"

zsh Ctrl-t:

smux-select-widget() {
  zle push-line
  BUFFER="smux select"
  zle accept-line
}
zle -N smux-select-widget
bindkey -M emacs '^T' smux-select-widget
bindkey -M viins '^T' smux-select-widget

Good first commands:

smux select
smux connect ~/code/myapp
smux connect --template rust ~/code/myapp
smux doctor

smux select behaves like this:

  • inside a tmux popup wrapper, it appears in the popup
  • inside a tmux pane, it runs fzf in that pane
  • outside tmux, it runs fzf in the terminal

Common Workflows

Jump to an existing session:

smux select

Connect a directory and let smux create or reuse the matching tmux session:

smux connect ~/code/myapp

Force a specific template for a directory:

smux connect --template rust ~/code/myapp

Choose a template interactively from the selector:

smux select --choose-template

Launch a saved project definition:

smux select

Projects Vs Templates

smux separates reusable layout from concrete workspace definitions:

  • template: a reusable tmux layout with windows, panes, layouts, startup behavior, and default commands
  • project: a concrete named workspace with a known path, optional session name, and either a template reference or its own tmux definition

Use templates when you want to reuse the same shape across many folders. Use projects when you want one named workspace that already knows where it lives and how it should start.

Picker Behavior

The unified picker combines:

  • tmux sessions
  • saved projects
  • zoxide directories

The template picker is separate and appears only when --choose-template is used.

Current behavior:

  • prompt is shown at the top
  • Esc cancels cleanly
  • the current tmux session is highlighted when smux select runs inside tmux
  • typing still does normal fuzzy search
  • Ctrl-X resets to the full list
  • Ctrl-S limits the main picker to sessions
  • Ctrl-P limits the main picker to projects
  • Ctrl-F limits the main picker to folders
  • Ctrl-T limits the template picker to templates

If you use a Nerd Font, smux can show colored icons for sessions, projects, folders, and templates.

Configuration

The main config has two top-level sections:

  • settings
  • templates

Project files in projects/*.toml define concrete workspaces.

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

Example main config:

[settings]
default_template = "default"
icons = "auto"

[settings.icon_colors]
session = 75
directory = 108
template = 179
project = 81

[templates.default]
startup_window = "main"
windows = [{ name = "main" }]

[templates.rust]
startup_window = "editor"
startup_pane = 0
windows = [
  { name = "editor", pre_command = "source .venv/bin/activate", command = "nvim" },
  { name = "run", synchronize = true, layout = "main-horizontal", panes = [
      { command = "cargo run" },
      { layout = "right 40%", command = "cargo test" },
    ] },
]

Example project file:

path = "~/code/example"
session_name = "example"
template = "rust"

Save that as:

~/.config/smux/projects/example.toml

For the full config reference, see:

That reference also includes layout recipes such as:

  • 2x2 grid windows
  • one large top pane with two bottom panes
  • sidebar layouts
  • vertical pane stacks

Commands

smux select [--choose-template] [--no-project-detect] [--config <path>]
smux connect [--template <name>] [--session-name <name>] [--config <path>] <path>
smux switch <session>
smux list-sessions
smux list-templates [--config <path>]
smux list-projects [--config <path>]
smux doctor [--config <path>]
smux init [--config <path>]
smux completions zsh [--dir <path>]
smux man [--dir <path>]

Completions And Man Pages

zsh completions:

smux completions zsh
smux completions zsh --dir ~/.local/share/zsh/site-functions

man pages:

smux man
smux man --dir ~/.local/share/man/man1

This includes the config man page:

smux-config.5