sessionizer

Select a new tmux session from a list of running sessions or a selection of projects.

[!WARNING] Very much a work in progress. As it is, it's probably only working for me. Configurability might come later.

Installation

[!IMPORTANT] Windows is not supported. Using WSL might work, though it is not tested.

Via Cargo

Released version

cargo install sessionizer

Development version

cargo install --git https://github.com/knutwalker/sessionizer

From source

make; make install

These steps might have to be adapted to your environment (e.g. elevating privileges for make install). On macOS, you have to use gmake from homebrew.

Quick start

$ sessionizer

Usage

sessionizer allows you to quickly create and switch to multiple tmux sessions.

It is meant for people who want to manage their various projects as separate tmux session, each containing their own list of windows and tools. This is in contrast to having one tool (say, neovim) and manage different sessions in that tool.

Workflow

Invoking sessionizer searches a set of paths for directories that would make a good project directory.

sessionizer will list open tmux sessions as well as all the directories in an fzf like interface (fzf does not need to be installed and is not used under the hood).

If an existing session is selected, sessionizer will either attach to that session or switch the client to that session, depending on whether you are currently inside a session or not.

When a directory is selected, sessionizer will create a new session for that project. The session will use the directory as their default directory (the location that is used for new windows/panes).

In addition, two environment variables are set:

• SESSION_NAME: How the tmux session is named
• SESSION_ROOT: The selected directory (e.g. cd $SESSION_ROOT will go to the directory)

Search path configuration

sessionizer reads the environment variable SESSIONIZER_PATH to determine the search paths. The value of SESSIONIZER_PATH is a colon-separated list of paths, similar to the PATH environment variable.

A path that is listed in SESSIONIZER_PATH will be suggested as a project directory. In order to search that path and also suggest subdirectories, special path components _ and * are used as wildcards.

The following rules govern how the syntax is used to define how a path is being searched:

• Each component of the path is traversed, but not matched.
• A path must begin with a regular component and cannot be empty
• A leading ~ is expanded to the user’s home directory
• A path ending in a regular component will be used directly
• If a path contains a wildcard, it will be used as a starting point for a search, but is not included directly
• The wildcard _ traverses any path on that level, but doesn’t include it
• The wildcard * traverses and includes any path on that level
• The wildcards must be their own component (e.g. *_ means a regular component *_)
• \ can be used to escape a wildcard (e.g. \_ will traverse the directory called _ as regular component)
• A _ wildcard must be followed by either an _ wildcard or a * wildcard
• A * wildcard may be followed by another * wildcard

Examples

Fallback behavior

If SESSIONIZER_PATH is not set, sessionizer will use CDPATH instead. In this case, each entry and treat every path as if it had a * wildcard at the end and will skip paths that are not absolute.

If CDPATH is also unset, sessionizer will query zoxide for a list of directories using zoxide query --list.

If zoxide is not installed, sessionizer will use ~/.config/* as a fallback and print a warning.

Useful integrations

TMUX

To open sessionizer from within tmux using <prefix> <C-f>, add the following to your ~/.tmux.conf:

bind-key -r C-f run-shell 'tmux neww sessionizer'

Note that this is not required for sessionizer to work. You can also run it directly from the shell.

Neovim

To open sessionizer from inside neovim using <C-f>, you can add the following to your config:

vim.keymap.set("n", "<C-f>", "<cmd>silent !tmux neww sessionizer<CR>")

I tend to always have neovim open inside tmux and tend to use the keybinding mentioned above instead of the neovim one. I find that it is more likely to have a keybind conflict in neovim than in tmux.

Alacritty

To use sessionizer as “shell” or entry point for alacritty, add the following to your alacritty.toml:

[shell]
program = "/opt/homebrew/bin/bash" # ! Change this to your shell
args = ["--login", "-c", "/usr/local/bin/sessionizer"] # ! Change this to the path of your sessionizer

Shell

I have the following aliases in my shell:

alias z='sessionizer --quiet'
alias zz='sessionizer --quiet --tmux-only'
alias cdsessionroot='cd $SESSION_ROOT'

The first one allows me to type z to open sessionizer. The second one allows me to type zz to open only running tmux sessions in sessionizer. The last one allows me to quickly change to the session root directory (the surrounding single quotes ' are important so that the value is resolved lazily).

Session initialization

sessionizer can be instructed to run some code and customization whenever a new session is created. This can be done by crating on of two files.

[!NOTE] Session initialization is completely optional. sessionizer can also be used directly without any configuration.

TOML initialization

To customize the session using TOML, create a file that is:

• located in the session root
• called either .sessionizer.toml or sessionizer.toml (If both are present, the dotted file takes precedence)
• has permissions 0400, 0600, or 0700

The TOML file has the following structure (see example/sessionizer.toml):

[env]
ENV_VAR_NAME = "env var value"

[[windows]]
name = "window name"
dir = "window path"
command = "window command"
remain = true

[[run]]
command = "command to run"

[env] section

The [env] section is a table of key value pairs. They define additional environment variables that will be set for every window in the session.

[!IMPORTANT] The values of these variables are visible outside of tmux by inspecting the program invocation. Keeping sensitive information (such as API keys) may be exposed to other users on the same machine.

[[windows]] section

[windows] is an array of tables. New entries can be added by using the [[windows]] syntax, which can be repeated multiple times.

For every entry in the [[windows]] array, a new tmux window will be spawned. That window will always spawn in the background.

The table for each [[windows]] section supports the following keys:

[[windows.on_exit]]

The value for on_exit can be either a boolean or a string and allows the following values:

on_exit is only interpreted when a command is set, otherwise it has no effect.

[[run]] section

[run] is an array of tables. New entries can be added by using the [[run]] syntax, which can be repeated multiple times.

For every entry in the [[run]] array, a new command will be executed in the first tmux window of the new session.

The table for each [[run]] section supports the following key:

[!NOTE] This option is similar to using a command for a new [[windows]] with the on_exit option set to keep.

Script based initialization

To customize the session using script file, create a file that is:

• located in the session root
• called either .sessionizer.init or sessionizer.init (If both are present, the dotted file takes precedence)
• has permissions 0500, or 0700

[!NOTE] If both, the TOML and the script file are present, the TOML file takes precedence and the script file will be ignored. In order to use both files, add a [[run.command]] with the value source .sessionizer.toml to the TOML file.

The file is basically a shell script that will be sourced in the new session. It can contain any command that you would otherwise type in the shell when starting a session.

[!TIP] To get support in vim/neovim, you can add the modeline # vim: set ft=bash:. You can adjust the ft based on the shell you are using.

Inspiration

sessionizer started of as a more personalized workflow of The Primeagen’s tmux-sessionizer.

All additions and modification are based on my personal preferences. I will likely not add features if I don’t find myself wanting or using them (e.g. I typically don’t care about predefined layout and panes, so there is no support for those).

License

sessionizer is licensed under either of the following, at your option:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)