-
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
# 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.tuxmuxBash
Add this to the end of your config file (usually ~/.bashrc):
eval "$(tux completion bash)"Elvish
Add this to the end of your config file (usually ~/.elvish/rc.elv):
eval (tux completion elvish | slurp)Fish
Add this to the end of your config file (usually ~/.config/fish/config.fish):
tux completion fish | sourcePowershell
Add this to the end of your config file (find it by running echo $profile in PowerShell):
Invoke-Expression (& { (tux compltion powershell | Out-String) })Zsh
Add this to the end of your config file (usually ~/.zshrc):
eval "$(tux completion zsh)"|
Important
|
For completions to work, the above line must be added after compinit is called. You may have to rebuild your completions cache by running rm ~/.zcompdump*; compinit. |
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.
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.
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.
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.
Tuxmux uses KDL as its configuration language.
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.
| Local | Global |
|---|---|
|
|
|
|
|
|
Values defined in the local config file have presidence over global values. Values containing lists will be merged instead of overritten.
Full list of values defined in config.kdl.
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 trueWorkspace 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"
}Configure the list of search paths used to search for valid workspaces. Tux uses these valid workspaces as options to attach to.
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"
}
}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"
}
}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.