Tuxmux

Tuxmux (tux) is a session and window manager for tmux.

Features

• Fuzzy find tmux sessions to create / attach.

• Jump list to quickly open tmux sessions (harpoon like)

• Keybinding support for jumping

• Highly configurable

• Support git worktrees on session creation

Installation

Cargo

cargo install tuxmux

Nix

# Try out tuxmux with `nix run`
nix run github:EdenEast/tuxmux

# Create a devshell with `nix shell`
nix shell github:EdenEast/tuxmux

# Install into profile
nix profile install github:EdenEast/tuxmux

# Install from nixpkgs
nix-env -iA nixpkgs.tuxmux

Source

cargo install --path .

Completion

Add this to the end of your config file (usually ~/.bashrc):

eval "$(tux completion bash)"

Add this to the end of your config file (usually ~/.elvish/rc.elv):

eval (tux completion elvish | slurp)

Add this to the end of your config file (usually ~/.config/fish/config.fish):

tux completion fish | source

Add this to the end of your config file (find it by running echo $profile in PowerShell):

Invoke-Expression (& { (tux compltion powershell | Out-String) })

Add this to the end of your config file (usually ~/.zshrc):

eval "$(tux completion zsh)"

Nix

If installed with nix the following are installed by default:

• Bash

• Fish

• Zsh

Jumplist

Tuxmux includes a feature known as the "Jump List," which is designed to streamline the process of navigating and attaching to different sessions quickly. This concept is inspired by the "harpooning" concept introduced in ThePrimeagen/harpoon. The Jump List serves as a powerful tool to facilitate seamless interaction with multiple sessions.

What is Harpooning?

Harpooning is a concept from ThePrimeagen’s GitHub project, which involves quickly and efficiently attaching to different sessions or targets within a terminal environment. It’s a technique often used by developers and power users who work with multiple terminal sessions simultaneously.

Using the Jump List

The primary use case for the Jump List is to enable quick access and attachment to specific sessions through keybindings. Here’s how it works:

Populating the Jump List
Before you can use the Jump List, you need to populate it with the sessions you want to interact with. This can typically be done by defining a set of sessions or targets within your application’s configuration.

# Appends the path argument to the jumplist
tux jump --path ~/.config/nvim

# Append the current path to the jumplist
tux jump --path .

# Open the jumplist in your $EDITOR
tux jump --edit

Navigating with Keybindings
Once the Jump List is populated, you can use keybindings or keyboard shortcuts to navigate to a specific index within the list. Each index typically corresponds to a session or target. This allows you to jump to a desired session with a single key combination.

# Bind homerow keys to tuxmux jumplist indices
bind-key -r J   run-shell "tux jump --index 1"
bind-key -r K   run-shell "tux jump --index 2"
bind-key -r L   run-shell "tux jump --index 3"
bind-key -r '"' run-shell "tux jump --index 4"

Seamless Session Attachment
When you activate a specific index in the Jump List, the application will swiftly attach you to the corresponding session, streamlining the process of interacting with multiple sessions efficiently.

Git Worktree

This application offers support for Git worktrees, allowing you to manage multiple worktrees within a Git repository more efficiently. When creating a Tmux session using this application, you’ll have the flexibility to choose which worktree to attach to if the repository contains multiple worktrees.

When you create a Tmux session with this application, you may encounter situations where the Git repository contains multiple worktrees. To provide you with a seamless experience, the application will prompt you to choose which worktree you’d like to attach to within the Tmux session.

Configuration

Tuxmux uses KDL as its configuration language.

Quickstart:

mkdir -p ~/.config/tuxmux
tux --default-config > ~/.config/tuxmux/config.kdl

File locations

Tuxmux loads configuration information from two types of sources, local and global. The file is determined by searching each path for the first config.kdl file.

Values defined in the local config file have presidence over global values. Values containing lists will be merged instead of overritten.

Options

Full list of values defined in config.kdl.

depth

Sets the maximux search depth for workspace paths.

Type: number
Default: 5

depth 3

height

Height of the fuzzy finder selection window. The value can be either a number or a string. A number represents the number of lines or entries to be displayed. A string can be either the string "full" meaning fullscreen or a number followed by a '%' (percent sign). The percentage is the percentage of the terminals hight to be used.

Type: string | number
Default: 50%

height 10

default_worktree

Select the repositories remote default branch if multiple worktrees are found. If the default worktree cannot be found the fallback will be to select the correct one.

Type: boolean
Default: false

default_worktree true

exclude_paths

Workspace directory crawler will prune the paths containing any of these components.

Optional arguments:

• default: (boolean) Append to default value if true (Default: true)

Type: string list
Default: { - ".direnv" "node_modules" }

exclude_paths default=false {
  - ".direnv"
  - "node_modules"
}

paths

Configure the list of search paths used to search for valid workspaces. Tux uses these valid workspaces as options to attach to.

paths.workspace

Workspace paths are paths to recursivly search to find valid workspaces. Tux will recursivly search the workspace paths until the max depth is reached. To override the default workspace value set optional default=false

Optional arguments:

• default: (boolean) Append to default value if true (Default: true)

Type: string list
Default: { - "~" }

paths {
  workspaces default=false {
    - "~/code"
  }
}

paths.single

Single paths are paths that are added to the list of valid workspace paths. This is useful if you want to add a path that would not be defined as a valid workspace.

Optional arguments:

• default: (boolean) Append to default value if true (Default: true)

Type: string list
Default: {}

paths {
  single default=false {
    - "~/.config/nvim"
  }
}

Development

Tuxmux is currently under development and subject to change before a v1 release. Have an idea for tuxmux? Open an issue or fork the project and create a PR.

Tuxmux was originally a shell script in my dotfiles and has grown into this utility program.

Licence

Tuxmux is licensed under Apache License (Version 2).

See LICENSE file for more details.