Tmux Workspace Manager
Yes - I was originally inspired to start using something to manage my tmux sessions by ThePrimeagen's tmux-sessionizer script. I used it for a bit, but wanted something more, that did a bit more.
That led me to tmuxinator. I thought the concept of layouts was really cool, and it felt nice to use, but there are several drawbacks that are addressed by dmux.
Honestly I like dmux quite a bit but for some reason was annoyed by a dependency on fzf. After that I found the dependencyless tmux-sessionizer that uses the Skim rust crate instead.
I felt like something for my workflow was missing from each of these, hence this thing.
- Fuzzy find workspaces to open in tmux
- Is able to open workspaces in tmux even if not run from within a tmux session
- Highly configurable
- Define different default behaviors for different workspace types
- Sets useful environment variables (prefixed with
TWM_) within your sessions to simplify extendingtwm's functionality with other scripts
I've explicitly avoided adding anything to twm that can be easily accomplished with scripts or other tools to a) avoid bloating this codebase and b) not force my workflow on anyone else.
With that said, if it is possible but particularly difficult to accomplish something with other tools, I'm open to adding it.
Examples of things that definitely won't be added:
- Killing a workspace session and opening the most recent/default/etc one. Very simple shell script.
Example I'm on the fence about:
- Support for git worktrees.
tmux-sessionizerhas this, but I don't like how it's implemented. I have my own script for handling worktrees, but I don't particularly love it either, and it's not a trivial script. I do like it better though.
twm (tmux workspace manager) is a customizable tool for managing workspaces in tmux sessions.
Workspaces are defined as a directory matching any workspace pattern from your configuration. If no configuration is set, any directory containing a `.git` file/folder or a `.twm.yaml` file is considered a workspace.
Usage: twm [OPTIONS]
Options:
-l, --layout
Prompt user to select a globally-defined layout to open the workspace with.
Using this option will override any other layout definitions.
-p, --path <PATH>
Open the given path as a workspace.
Using this option does not require that the path be a valid workspace according to your configuration.
-n, --name <NAME>
Force the workspace to be opened with the given name.
twm will not store any knowledge of the fact that you manually named the workspace. I.e. if you open the workspace at path `/home/user/dev/api` and name it `jimbob`, and then open the same workspace again manually, you will have two instances of the workspace open with different names.
-d, --dont-attach
Don't attach to the workspace session after opening it
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
twm will set several environment variables within all sessions generated by it. They're there to help with scripts or keybinds you want to interact with twm. They are:
TWM- set to1if the current shell is in atwmsessionTWM_ROOT- the root directory of the new workspaceTWM_TYPE- the type of workspace. empty string if there was no workspace type defined.TWM_NAME- the name of the tmux session created bytwm.
Example use cases:
- keybind or alias to return to the root of the current workspace
The easiest way to install is to use Cargo:
cargo install twmIt is also available on NixOS via nixpkgs
See CONFIGURATION.md
# ~/.tmux.conf
bind-key -r f run-shell "tmux neww twm"
bind-key -r F run-shell "tmux neww twm -l"
bind-key -r e run-shell "tmux switch -t $TWM_DEFAULT" # i set TWM_DEFAULT in my shellrcContributions are more than welcome! If there are workflows you think would be useful to add, or if you find a bug, please open an issue or PR. For style and linting, I simply use cargo fmt and clippy::all.