TWM is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install twm

It will make the twm command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall twm uninstalls.

Adding `twm` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add twm

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

twm = "0.13.0"

The twm library will be automatically available globally. Read the twm library documentation.

Back to the crate overview.

Readme

twm

Tmux Workspace Manager

twm is a highly performant, customizable tool to manage workspaces as tmux sessions. Sensible defaults can get you up and running with zero configuration, or you can set it up to fit any workflow you like.

twm

CLI Usage

Installation Instructions

Exposed Environment Variables

Configuring twm

Configuration Recipes

Contribution Guidelines

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.

Environment variables that affect twm:

TWM_CONFIG_FILE: Path to the configuration file to use. Overrides the default search locations.

Environment variables that twm sets in tmux sessions:

TWM: set to 1 to indicate that you're in a twm-managed session

TWM_ROOT: the root directory of the workspace

TWM_TYPE: the type of workspace, as defined in your configuration via the "name" on workspace definitions

TWM_NAME: the name of the session at creation time

Usage: twm [OPTIONS]

Options:
  -e, --existing
          Prompt user to select an existing tmux session to attach to.

          This shouldn't be used with other options.

  -g, --group
          Prompt user to start a new session in the same group as an existing session.

          Setting this option will cause `-l/--layout` and `-p/--path` to be ignored.

  -G, --group-with <GROUP_WITH>
          Group with an existing session by name

  -d, --dont-attach
          Don't attach to the workspace session after opening it

  -l, --layout
          Prompt user to select a globally-defined layout to open the workspace with.

          Using this option will override any other layout definitions that would otherwise automatically be used when opening the workspace.

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

          When setting this option, you should be aware that twm will not "see" this session when performing other automatic actions. For example, if you have a workspace at ~/foobar and run `twm -n jimbob -p ~/foobar`, and then run `twm` and select `~/foobar` from the picker, a new session `foobar` will be created. If you then run `twm -g` and select `foobar`, `foobar-1` will be created in the `foobar` group.

  -N, --print-workspace-name
          Print the name of the workspace generated for the given path to stdout.

          This can be used with other options.

  -c, --command <COMMAND>
          Override any layouts and open the workspace with the given command instead

      --make-default-config
          Make default configuration file.

          By default will attempt to write a default configuration file and configuration schema in `$XDG_CONFIG_HOME/twm/` Using `-p/--path` with this flag will attempt to write the files to the folder specified. twm will not overwrite existing files. You will be prompted to rename/move the existing files before retrying.

      --make-default-layout-config
          Make default local layout configuration file.

          Will attempt to create `.twm.yaml` in the current directory. Will not overwrite existing files. You can use `-p/--path <PATH>` to specify a different directory to write the file to.

      --print-config-schema
          Print the configuration file (twm.yaml) schema.

          This can be used with tools (e.g. language servers) to provide autocompletion and validation when editing your configuration.

      --print-layout-config-schema
          Print the local layout configuration file (.twm.yaml) schema.

          This can be used with tools (e.g. language servers) to provide autocompletion and validation when editing your configuration.

      --print-bash-completion
          Print bash completions to stdout

      --print-zsh-completion
          Print zsh completions to stdout

      --print-fish-completion
          Print fish completions to stdout

      --print-man
          Print man(1) page to stdout

  -s, --search-paths <SEARCH_PATHS>
          Paths to search for workspaces in. Overrides paths set in configuration.

          Multiple paths can be specified by setting this flag multiple times, e.g. `-s ~/projects -s ~/work`.

  -D, --depth <DEPTH>
          Maximum depth to search for workspaces. Overrides max depth set in configuration

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

The twm-set environment variables can be useful in a variety of ways:

Instead of defining all your setup commands in a workspace-type-specific layout, you could have a 1 shared setup script defined globally that runs on workspace entry that checks TWM_TYPE for type-specific setup
You can use TWM_ROOT to perform actions if the workspace is in within a specific directory
You can check TWM to ensure you handle manually-created sessions differently than twm-created sessions in some automation task

Additionally, setting the TWM_CONFIG_FILE env var will override the default config search path. If your config file is in a non-standard location, you can test twm with the default configuration with TWM_CONFIG_FILE= twm, or if your configuration is in the standard location, TWM_CONFIG_FILE=/dev/null twm will do.

Installation

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.

Cargo

The easiest way to install is to use Cargo:

cargo install twm

Nix

If you use Nix, it is available in nixpkgs as well as being packaged in this repo's flake.

Completion

If you're using Nix, completion scripts are automatically installed with twm, both from this flake and nixpkgs.

I don't believe it is packaged on any other OS. You can manually set up shell completions by putting the following in your shell config:

Bash

# ~/.bashrc
eval "$(twm --print-bash-completion)"

Zsh

# ~/.zshrc
eval "$(twm --print-zsh-completion)"

Fish

# ~/.config/fish/config.fish
twm --print-fish-completion | source

Configuration

twm doesn't need any configuration to run. You can just install it and run twm, and the defaults should work for some.

To get a decent default configuration file, you can run twm --make-default-config, which will attempt to write two files: $XDG_CONFIG_HOME/twm/{twm.yaml,twm.schema.json}.

You can pass -p/--path <PATH> with --make-default-config to write the files to a different folder.

If you use yaml-language-server, the default configuration file will automatically be set up to use the twm.schema.json file for validation and completion.

When you update twm, you can run twm --print-config-schema > $XDG_CONFIG_HOME/twm/twm.schema.json to ensure you have the latest schema file.

For a full list of configuration options with examples, see CONFIGURATION.md

Configuration Validation Examples

Here's what the in-editor config validation looks like in neovim with using yaml-language-server:

twm configuration completion

twm configuration validation

Recipes

tmux keybindings

Here are the basic twm bindings I personally use:

# ~/.tmux.conf
bind f run-shell "tmux neww twm"
bind F run-shell "tmux neww twm -l"
bind s run-shell "tmux neww twm -e"  # i rebind the original `s` to `S` so I can still use it
bind g run-shell "tmux neww twm -g"
bind e run-shell "tmux switch -t $TWM_DEFAULT"  # i set TWM_DEFAULT in my shellrc, just a session that is always available as a scratch area

Scripting

Switching to a workspace from neovim

One thing I wanted to do was to be able to switch to a new workspace from my snacks.nvim dashboard's recent project selector.

-- ~/.config/nvim/lua/snacks/init.lua
-- ...
        action = function(project_path)
                local tmux = vim.fn.getenv("TMUX")
                if tmux == nil then
                        -- if not in tmux already, do something else, maybe just set cwd or something
                        return
                end
                -- -d to not attach, -N to print the session name to stdout, -p to use the path we selected in neovim, sub(1, -2) to remove the trailing newline
                local twm_workspace_name = vim.system({"twm", "-d", "-N", "-p", project_path}, {text = true}):wait().stdout:sub(1, -2)
                vim.system({"tmux", "switch-client"})
        end
-- ...

Start new shells in a "default" workspace

I like to make sure I'm always in tmux when I'm in the terminal, so I have something like this in my .zshrc

# ~/.zshrc
export TWM_DEFAULT="default"
tmux has-session -t $TWM_DEFAULT >/dev/null || twm -d -p $HOME -n $TWM_DEFAULT
if [ -z "$TWM" ]; then
        tmux switch -t $TWM_DEFAULT
fi

Useful shell aliases / functions I've used

# ~/.zshrc
alias twm-fork='twmg() { gh repo fork --clone --default-branch-only --remote "$1" "$2"; twm -p "$2"; }; twmg'  # fork repo $1 at path $2 and open it in twm

# kill current session and switch to last/next/previous session
# i bind this to K in tmux
kt() {
  ORIG_SESS="$TWM_NAME"
  tmux switch -l || tmux switch -n || tmux switch -p
  tmux kill-session -t "$ORIG_SESS"
}

Contributing

Contributions are of course welcome! It's not a huge project so I don't have a lot of guidelines. Make sure the tests (test*, for now :\) pass. cargo fmt. cargo clippy -- -D clippy::all. That's all I can think of.

Feature Philosophy

I avoid adding anything that doesn't have obvious value being inside twm. If something that can be done well with a simple shell script or similar, it probably should be.

Examples of things that won't be added:

Opening a fuzzy finder to choose a session to kill. Simple shell script / easy enough to do with built-in tmux features.
Opening git worktree branches in windows. Use layouts for this. Detect when you're in a workspace with worktrees and run a script to open them how you want. This will always be more flexible than anything that would be built in.
Cloning a git repository into a new workspace. This and the above are pretty specific to tmux-sessionizer but useful to highlight the differences in our goals. twm offers -p to open a workspace at a specific path, so such a functionality could be done with something as simple as an alias alias twm-clone='git clone $1 $2 && twm -p $2'. You can do the same with mercurial, svn, whatever you want to do.

Examples of things that could be added:

Support for different multiplexers (e.g. Zellij). Abstracting the tmux-specific parts of twm into something that could be set up with different multiplexer backends could be a great addition. But I only use tmux/nobody has asked, so I haven't bothered.

Features that snuck their way in

There are some features I originally didn't want to add but have since been added anyways.

Fuzzy finding existing sessions to attach to. Originally I figured it just makes more sense to leave that to built in tmux features, but when the request was made to add a feature to open a session in a group (twm -g), I had to add everything needed for twm -e anyways. Additionally, if you want to fuzzy find existing sessions, having that functionality outside twm would rely on some other fuzzy finder. Part of the point of twm coming with its own builtin finder is avoid having to rely on other tools in the first place. Thus twm -g and twm -e were born. I think -e is the least useful thing that will ever be added to twm.

License

MIT

Installing the command-line executable

Adding twm library as a dependency

Adding `twm` library as a dependency