twm

Tmux Workspace Manager

Another one?

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.

What features does it have?

• 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 extending twm'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-sessionizer has 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.

Usage

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

Environment Variables

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 to 1 if the current shell is in a twm session
• TWM_ROOT - the root directory of the new workspace
• TWM_TYPE - the type of workspace. empty string if there was no workspace type defined.
• TWM_NAME - the name of the tmux session created by twm.

Example use cases:

• keybind or alias to return to the root of the current workspace

Installation

The easiest way to install is to use Cargo:

cargo install twm

It is also available on NixOS via nixpkgs

Configuration

See CONFIGURATION.md

Example twm tmux keybindings

# ~/.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 shellrc

Contributing

Contributions 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.

License

GPL v2.0