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.
Important
Windows is not supported. Using WSL might work, though it is not tested.
cargo install sessionizercargo install --git https://github.com/knutwalker/sessionizermake; make installThese 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.
$ sessionizersessionizer 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.
Invoking sessionizer searches a set of paths for directories that would make a good project directory.
Caution
The heuristics for which paths are search and what makes a “good” project are currently based my personal preferences and will likely not work for others.
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 namedSESSION_ROOT: The selected directory (e.g.cd $SESSION_ROOTwill go to the directory)
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.
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.
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 sessionizerI 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).
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.
To customize the session using TOML, create a file that is:
- located in the session root
- called either
.sessionizer.tomlorsessionizer.toml(If both are present, the dotted file takes precedence) - has permissions
0400,0600, or0700
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"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] 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:
| key | usage | required | aliases |
|---|---|---|---|
name |
The name of new window (usually displayed in the tmux status bar) | No (but recommended, otherwise a name will be derived) | |
dir |
The base directory of that new window. Paths are relative to the session root | No (defaults to session root) | path, workdir, wd, pwd, cwd |
command |
A command to run inside the new window. | No | cmd, run |
on_exit |
What happens to the window when the command finishes (see below). | No (default behavior depends on the remain-on-exit setting in tmux) | keep-alive, remain |
The value for on_exit can be either a boolean or a string and allows the following values:
| values | usage |
|---|---|
"destroy", "kill", false |
Window will be destroyed after the command finishes. Using false might make more sense of the key is called remain. |
"keep", "shell", "stay", true |
Window will be kept alive and drop to the shell when the command finishes. Using true might make more sense of the key is called remain. |
"deactivate", "inactive", "remain" |
Window will be deactivated after the command finishes. It can be reactivated using the tmux command respawn-window (see man tmux for details) |
on_exit is only interpreted when a command is set, otherwise it has no effect.
[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:
| key | usage | required | aliases |
|---|---|---|---|
command |
A command to run inside the first window. | No | cmd, run |
Note
This option is similar to using a command for a new [[windows]] with the on_exit option set to keep.
To customize the session using script file, create a file that is:
- located in the session root
- called either
.sessionizer.initorsessionizer.init(If both are present, the dotted file takes precedence) - has permissions
0500, or0700
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.
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).
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)