Plugin which makes tmux work and feel like i3wm

Overview

Tmux Tilish

This is a plugin that makes tmux behave more like a typical dynamic window manager. It is heavily inspired by i3wm, and most keybindings are taken directly from there. However, I have made some adjustments to make these keybindings more consistent with vim: using hjkl instead of jkl; for directions, and using vim's definitions of "split" and "vsplit". There is also an "easy mode" available for non-vim users, which uses arrow keys instead of hjkl.

The plugin has been verified to work on tmux v1.9, v2.6, v2.7, v2.9, and v3.0. Some features are only available on newer versions of tmux (currently v2.7+), but I hope to provide at least basic support for most tmux versions in active use. If you encounter any problems, please file an issue and I'll try to look into it.

Why?

Okay, so who is this plugin for anyway? You may be interested in this if:

  • You're using or interested in using tmux, but find the default keybindings a bit clunky. This lets you try out an alternative keybinding paradigm, which uses a modifier key (Alt) instead of a prefix key (Ctrl + b). The plugin also makes it easier to do automatic tiling via tmux layouts, as opposed to splitting panes manually.
  • You use i3wm, but also do remote work over ssh + tmux. This lets you use similar keybindings in both contexts.
  • You also use other platforms like Gnome, Mac, or WSL. You want to take your i3wm muscle memory with you via tmux.
  • You're not really using i3wm anymore, but you did like how it handled terminals and workspaces. You'd like to keep working that way in terminals, without using i3wm or sway for your whole desktop.
  • You use a window manager that is similar to i3wm, e.g. dwm, and want to have that workflow in tmux too.

Quickstart

The easiest way to install this plugin is via the Tmux Plugin Manager. Just add the following to ~/.tmux.conf, then press Ctrl + b followed by Shift + i to install it (assuming default prefix key):

set -g @plugin 'jabirali/tmux-tilish'

For tmux v2.7+, you can customize which layout is used as default for new workspaces. To do so, add this to ~/.tmux.conf:

set -g @tilish-default 'main-vertical'

Just replace main-vertical with one of the layouts from the tmux man page:

Description Name
split then vsplit main-horizontal
only split even-vertical
vsplit then split main-vertical
only vsplit even-horizontal
fully tiled tiled

The words "split" and "vsplit" refer to the layouts you get in vim when running :split and :vsplit, respectively. (Unfortunately, what is called a "vertical" and "horizontal" split varies between programs.) If you do not set this option, tilish will not autoselect any layout; you can still choose layouts manually using the keybindings listed below.

After performing the steps above, you should read the list of keybindings. For further configuration options:

It is also recommended that you add the following to the top of your .tmux.conf:

set -s escape-time 0
set -g base-index 1

The first line prevents e.g. Esc + h from triggering the Alt + h keybinding, preventing common misbehavior when using vim in tmux. This option is automatically set by tmux-sensible, if you use that. The second line makes workspace numbers go from 1-10 instead of 0-9, which makes more sense on a keyboard where the number row starts at 1. However, tilish explicitly checks this setting when mapping keys, and works fine without it.

Keybindings

Finally, here is a list of the actual keybindings. Most are taken from i3wm. Below, a "workspace" is what tmux would call a "window" and vim would call a "tab", while a "pane" is what i3wm would call a "window" and vim would call a "split".

Keybinding Description
Alt + 0-9 Switch to workspace number 0-9
Alt + Shift + 0-9 Move pane to workspace 0-9
Alt + hjkl Move focus left/down/up/right
Alt + Shift + hjkl Move pane left/down/up/right
Alt + Enter Create a new pane at "the end" of the current layout
Alt + s Switch to layout: split then vsplit
Alt + Shift + s Switch to layout: only split
Alt + v Switch to layout: vsplit then split
Alt + Shift + v Switch to layout: only vsplit
Alt + t Switch to layout: fully tiled
Alt + z Switch to layout: zoom (fullscreen)
Alt + r Refresh current layout
Alt + n Name current workspace
Alt + Shift + q Quit (close) pane
Alt + Shift + e Exit (detach) tmux
Alt + Shift + c Reload config

The Alt + 0 and Alt + Shift + 0 bindings are "smart": depending on base-index, they either act on workspace 0 or 10.

The keybindings that move panes between workspaces assume a US keyboard layout. However, you can configure tilish for international keyboards by providing a string @tilish-shiftnum prepared by pressing Shift + 1234567890. For instance, for a UK keyboard, you would configure it as follows:

set -g @tilish-shiftnum '!"£$%^&*()'

Your terminal must support sending keycodes like M-£ for the above to work. For instance, a UK keyboard layout works fine on urxvt, but does not work by default on kitty or alacritty, which may require additional configuration.

Easy mode

To make the plugin more accessible for people who do not use vim as well, there is also an "easy mode" available, which uses arrow keys instead of the vim-style hjkl keys. This mode can be activated by putting this in your .tmux.conf:

set -g @tilish-easymode 'on'

The revised keybindings for the pane focus and movement then become:

Keybinding Description
Alt + Move focus left/down/up/right
Alt + Shift + Move pane left/down/up/right

Prefix mode

Note that this feature is currently only available in tmux v2.4+. The "prefix mode" uses a prefix key instead of Alt, and may be particularly interesting for users of editors like kak and emacs that use Alt key a lot. To activate this mode, you define a prefix keybinding in your tmux.conf. For instance, to use Alt + Space as your tilish prefix, add:

set -g @tilish-prefix 'M-space'

Actions that would usually be done by Alt + key are now accomplished by pressing the prefix and then key. For example, opening a split is usually Alt + Enter, but with the above prefix this becomes Alt + Space then Enter. Note that the tilish prefix is different from the tmux prefix, and should generally be bound to a different key. For the prefix key, you can choose basically any keybinding that tmux supports, e.g. F12 or C-s or anything else you may prefer.

All these keybindings are repeat'able, so you do not have to press the prefix key again if you type multiple commands fast enough. Thus, pressing Alt + Space followed by hj would move to the left and then down, without requiring another prefix activation. The tmux option repeat-time can be used to customize this timeout. Personally, I find the default 500ms timeout somewhat short, and would recommend that you increase this to at least a second if you use tilish:

set -g repeat-time 1000

Application launcher

In i3wm, the keybinding Alt+d is by default mapped to the application launcher dmenu, which can be practical to quickly open apps. If you have fzf available on your system, tilish can offer a similar application launcher using the same keyboard shortcut. To enable this functionality, add the following to your ~/.tmux.conf:

set -g @tilish-dmenu 'on'

Basically, pressing Alt+d will then pop up a split that lets you fuzzy-search through all executables in your system $PATH. Selecting an executable runs the command in that split. When you want to start an interactive process, this can be more convenient than using Alt+Enter and typing the command name. This is currently only available in tmux v2.7+.

Terminal compatibility

Not all terminals support all keybindings. The plugin has been verified to work well with: iTerm2 and Terminal.app on macOS; alacritty, kitty, terminator, gnome-terminal, and urxvt on Linux; wsltty and alacritty on Windows. Some of these terminals bind Alt+Enter to fullscreen, so you have to disable that for the tilish "new pane" binding to work. Moreover, gnome-terminal steals the "switch workspace" keybindings Alt+0-9 if you open multiple tabs. If you use macOS, you likely want to configure the Option key to send either Esc+ (iTerm2) or Meta (Terminal.app) under the keyboard settings of the app.

If you use xterm, almost none of the Alt keys work by default. That can be fixed by adding this to ~/.Xresources:

XTerm*eightBitControl: false
XTerm*eightBitInput: false
XTerm.omitTranslation: fullscreen
XTerm*fullscreen: never

Usage inside i3wm

If you use tilish inside i3wm or sway, keybindings like Alt+Enter may spawn a new terminal in your window manager instead of a new terminal pane inside tmux. The window manager always takes priority — so if both i3wm and tilish define the same keybinding, i3wm will intercept the keybinding before tmux sees it.

The best way to solve this is perhaps to change your window manager modifier key to Super, also known as the "Windows key". As described in the i3wm user guide, this can be done by changing $mod to Mod4 in your i3wm config. That way, pressing e.g. Alt+Enter opens a new terminal pane inside tmux, while Super+Enter opens a new terminal in i3wm.

Alternatively, tilish also supports a Prefix mode. This is in my opinion less ergonomic than the default tilish keybindings. However, it does not require the use of Alt, and is therefore compatible with the default i3wm keybindings.

Integration with vim

There are two great plugins tmux-navigate and vim-tmux-navigator, which both allow seamless navigation between vim splits and tmux splits. The former has an advantage that it also works over ssh connections, and that it plays better with zooming (Alt+z). If you use either plugin, you can tell tilish to make it setup the keybindings for you. (If you don't, tilish will use fallback keybindings that don't integrate with vim.)

Navigate

It is perhaps easiest to setup tmux-navigate. Just load navigate after tilish in your tmux.conf, and set the option @tilish-navigate to on to integrate them. Thus a full working minimal example of a tpm-based tmux.conf would be:

# List of plugins.
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'jabirali/tmux-tilish'
set -g @plugin 'sunaku/tmux-navigate'

# Plugin options.
set -g @tilish-navigate 'on'

# Install `tpm` if needed.
if "test ! -d ~/.tmux/plugins/tpm" \
   "run 'git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm && ~/.tmux/plugins/tpm/bin/install_plugins'"

# Activate the plugins.
run -b "~/.tmux/plugins/tpm/tpm"

No further setup is required; tilish sets up the keybindings, and navigate handles seamless navigation of vim/nvim splits. However, if you also want this seamless navigation over ssh connections, you should install the accompanying vim plugin; see their website for more information.

Navigator

To install vim-tmux-navigator, you should first install the plugin for vim or nvim, as described on their website. Then place this in your ~/.config/nvim/init.vim (nvim) or ~/.vimrc (vim):

noremap <silent> <m-h> :TmuxNavigateLeft<cr>
noremap <silent> <m-j> :TmuxNavigateDown<cr>
noremap <silent> <m-k> :TmuxNavigateUp<cr>
noremap <silent> <m-l> :TmuxNavigateRight<cr>

You then just have to tell tilish that you want the integration:

set -g @tilish-navigator 'on'

A minimal working example of a ~/.tmux.conf with tpm would then be:

# List of plugins.
set -g @plugin 'tmux-plugins/tpm'
set -g @plugin 'tmux-plugins/tmux-sensible'
set -g @plugin 'jabirali/tmux-tilish'

# Plugin options.
set -g @tilish-navigator 'on'

# Install `tpm` if needed.
if "test ! -d ~/.tmux/plugins/tpm" \
   "run 'git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm && ~/.tmux/plugins/tpm/bin/install_plugins'"

# Activate the plugins.
run -b "~/.tmux/plugins/tpm/tpm"

Related projects

Comments
  • Alt+Shift+q on last pane freezes the terminal

    Alt+Shift+q on last pane freezes the terminal

    First of all, this is my fav tmux plugin so far. Thanks for making this. :heart:

    Pressing Alt+Shift+q freezes the last tmux pane for me, I have to close the terminal completely as It refuses to listen to keyboard. It works fine if there is more than one pane open.

    Info

    OS: Manjaro Linux x86_64
    Kernel: 5.6.10-3-MANJARO
    Shell: zsh 5.8
    Terminal: Konsole
    Tmux: 3.1
    
    opened by numToStr 5
  • Don't rename tmux windows on window close

    Don't rename tmux windows on window close

    Please add an option where tmux windows aren't renamed just because a window was closed. E.g. currently if I have Window 1 and Window 2 and I close Window 1, Window 2 will be renamed to Window 1.

    Renaming the windows in this way throws off my muscle-memory, e.g. I'm used to switching to Window 9 for server state and Window 10 (0) for overall system state, with lower-number windows for coding and running individual programs.

    BTW, I'm coming from XMonad, which has the desired behavior by default.

    Thanks for making this awesome tool!

    opened by emchristiansen 4
  • Fullscreen shortcut conflicts with bindkey forward-word

    Fullscreen shortcut conflicts with bindkey forward-word

    Thanks for this great project, after having to give up i3 to switch to MacOS, tmux-tilish makes me feel right at home again.

    I just wanted to report that the following configuration conflicts with the bindkey to move to the next word in the shell (MacOS): bind_layout "${mod}f" 'fullscreen'

    It would be great to mention the issue in the documentation to help users to diagnose and fix the issue (in my case I remap it to ${mod}z to be consistent with standard tmux).

    Thanks!

    opened by ryepesg 3
  • Key binding question

    Key binding question

    Hi. This plugin looks so interesing. Before trying, let me ask a question.

    As far as I understanding, this plugin let users to use same keybindings as i3wm in tmux, which would be cool. However, I'm wondering how you can prioritize.

    I'm using i3wm and tmux together. So in a tmux pane, if I hit alt+<left>, for example, which one does take the key? i3wm or tmux?

    • If tmux hijacks the key, how can I move to left i3wm window?
    opened by ywpkwon 3
  • Nested tmux

    Nested tmux

    Is there a way to make this work with nested tmux sessions? I would like to navigate around panels in the inner session. Currently, I can just navigate in the outer tmux. Both session use the same (mounted) config file.

    BR

    opened by chuber1986 2
  • Vim buffers

    Vim buffers

    First of all, let me say that this is an awesome plugin!

    As a user of i3, I found it really uncomfortable to be forced to connect to my work VM via VNC, in an environment that doesn't (easily) allow usage of i3, and also suffer through slow responsiveness when connecting from home. It's to be able to have something similar via ssh.

    Now for my question, I wish to use vim buffers the same way I use it between terminals. for example: 'ctrl + " + *', but it seems that when pasting, it grabs whatever is in the clipboard of the local machine, is there a way to get this to work as it would between local terminals?

    opened by ytmhub 2
  • Does `tmux-tilish` work on MacOS on M1 processors?

    Does `tmux-tilish` work on MacOS on M1 processors?

    I have the same config on both an Intel Mac and an M1 Mac, and tmux-tilish works on the former but not the latter. Is it tested on M1?

    BTW, I'm also using tmux-continuum and it appears to work. I installed tmux with brew.

    opened by emchristiansen 1
  • Additional instructions needed for iTerm2

    Additional instructions needed for iTerm2

    To make the Alt / Option key work properly in iTerm2, I had to change its behavior from "Normal" to "Esc+" in Profiles -> Keys. Consider adding this to the README.

    Screen Shot 2021-07-14 at 11 59 16 AM

    opened by emchristiansen 1
  • Apply suggestions from `shellcheck`

    Apply suggestions from `shellcheck`

    I applied suggestions from shellcheck, a shell script static analysis tool.

    I disabled the following errors:

    • SC2003: expr is antiquated. Consider rewriting this using $((..)), ${} or [[ ]].

      You use expr a lot, but I'm not familiar with it or how I'd rewrite it as shellcheck suggests.

    • SC2016: Expressions don't expand in single quotes, use double quotes for that.

      I believe these errors are false positives. shellcheck might not understand when you want the $variables to be evaluated in the shell being invoked (e.g. sh -c 'echo $USER').

    • SC2250: Prefer putting braces around variable references even when not strictly required.

      This error is optional, but I have all errors enabled on my machine. This was the only optional error it complained about. I disabled it to avoid disrupting the code more than necessary.

    opened by evanrelf 1
  • Fix moving panes to workspaces in prefix mode on strict POSIX shells

    Fix moving panes to workspaces in prefix mode on strict POSIX shells

    Hello, and thank you for this nice plugin. I found that on my machine, I was unable to move panes between windows in prefix- mode. I would like to provide this patch that fixes the issue for me. I have tested it on a MacBook Pro and on an Arch Linux box.

    The "expr substr" syntax used to return characters from a string is not defined in the POSIX sh specication. Attempting to use that syntax on a Macbook led to the bindings for moving panes between windows in prefix mode to fail to be bound.

    This patch addresses this by using a POSIX-compliant replacement for returning a character from a string by index using the cut command.

    opened by epaulson10 1
  • Updating shebang to indicate POSIX compatibility

    Updating shebang to indicate POSIX compatibility

    Because this script doesn't use any bashisms, it should be fully POSIX-compatible. Giving it the header /bin/sh indicates this, and means that people who have dash symlinked in this location can take advantage of its extra speed.

    I'm familiar with purpose of using the #!/usr/bin/env bash for Mac compatibility, and in this case using /bin/sh shouldn't cause any issues, again because it's a POSIX-compliant script. It all worked fine when I tested it on my MBP. Thanks for writing this!

    opened by Keating950 1
  • Can't get this to do anything in iTerm2 on macOS

    Can't get this to do anything in iTerm2 on macOS

    Hi,

    Came across this plugin and was instantly interested.

    Setup the config but it doesn't seem to be doing anything. I'm not sure if I'm using it wrong.

    What isn't clear from the docs is if I still need to use the tmux prefix? I am trying to spawn a new pane using C-b, option+enter. I have the config set to tiled. I'm assuming this is the master/stack layout?

    Thanks,

    D

    opened by damienbutt 1
  • preserve pane arrangement on refresh

    preserve pane arrangement on refresh

    Hello!

    I have been using this plugin for nearly a year now and it has been a tremendous productivity gain for me.

    However, it always bugged me that when I accidentally apply a preset layout, I would basically lose the ability to configure the pane arrangement of that window and need to move all my precious panes to another window.

    I thought this was intentional, but maybe not?

    Thanks and great project!

    opened by augustfengd 0
  • alacritty macos keys don't work properly

    alacritty macos keys don't work properly

    need to do some development on a mac and am trying to replicate my linux setup as well as possible. alt+enter works alright, but alt+printable character does not. any ideas?

    opened by dvc94ch 4
  • Ability to customize keybindings

    Ability to customize keybindings

    Hi,

    I installed the plugin and I'm enjoying it, thank you :+1:

    However, I was wondering if you plan to allow customizing the bindings through options. For example, a tool that I'm using is using Alt + v to do something, and that key is used by tilish.

    I know there's the possibility of using the "prefix mode", but that would be somehow slower than using the Alt key combination. So I was wondering if it's possible to have something like this:

    There are some defaults defined for keys, for example v and V, but they can be overridden using an option; something like set -g @tilish-vlayout = ... and set -g @tilish-vshiftlayout = ... (ignore the option names :smile: )

    opened by farzadmf 15
Owner
Jabir Ali Ouassou
Jabir Ali Ouassou
Slice and dice your TMUX windows and panes

chaakoo Introduction Configuration Using Chaakoo Examples Download License Introduction Chaakoo is a wrapper over TMUX that can create sessions, windo

Pallav Jha 85 Nov 1, 2022
go program that installs and customizes ohmyzsh tmux vim via various plugins and other nice to haves

Pimp-My-Shell Table of Contents Pimp-My-Shell Install Usage About Resources Tmux Hotkeys VIM Hotkeys Adjusting Custom Aliases Mac Fix Terminal bind ke

null 23 Dec 22, 2022
Trzsz-go - A simple file transfer tools, similar to lrzsz ( rz / sz ), and compatible with tmux

Trzsz-go - A simple file transfer tools, similar to lrzsz ( rz / sz ), and compatible with tmux

null 362 Dec 31, 2022
Minutes is a CLI tool for synchronizing work logs between multiple time trackers, invoicing, and bookkeeping software to make entrepreneurs' daily work easier.

Minutes is a CLI tool for synchronizing work logs between multiple time trackers, invoicing, and bookkeeping software to make entrepreneurs' daily work easier.

Gábor Boros 21 Aug 8, 2022
Rem is a CLI trash which makes it ridiculously easy to recover files.

Rem is a CLI trash which makes it ridiculously easy to recover files. We've all had that moment when we've deleted something we realised we shouldn't have. It sucks. Let's fix that!

Ishan Goel 45 Dec 21, 2022
I like reading news but I also like the terminal. I am leaning and practicing my go.

I made an api and didn't know how to use it. Screenshots The initial screen when you first run the app. The screen after you specify an id. This app u

Daniel M. Matongo 2 Jan 14, 2022
A simple command line tool using which you can skip phone number based SMS verification by using a temporary phone number that acts like a proxy.

Fake-SMS A simple command line tool using which you can skip phone number based SMS verification by using a temporary phone number that acts like a pr

Narasimha Prasanna HN 754 Dec 31, 2022
ls Xtended : A command line utility which lets you navigate through terminal like a pro 😎.

Navigate through terminal like a pro ?? ?? Demo • ⚗️ Installation • ?? Contribution • ❗ Known Issues ❓ Why? It's a pain to cd and ls multiple times to

Souvik 170 Dec 14, 2022
Go-file-downloader-ftctl - A file downloader cli built using golang. Makes use of cobra for building the cli and go concurrent feature to download files.

ftctl This is a file downloader cli written in Golang which uses the concurrent feature of go to download files. The cli is built using cobra. How to

Dipto Chakrabarty 2 Jan 2, 2022
ghcv-cli makes it easy to view the user-created issues, pull requests, and repositories in the terminal.

ghcv-cli ghcv-cli makes it easy to view the user-created issues, pull requests, and repositories in the terminal. About Show a list of pull requests c

Kyosuke Fujimoto 14 Mar 13, 2022
A tiny markup language for terminal output. Makes formatting output in CLI apps easier!

tml - Terminal Markup Language A Go module (and standalone binary) to make the output of coloured/formatted text in the terminal easier and more reada

Liam Galvin 705 Dec 14, 2022
A go cli makes it easy to get quotes from the Ted Lasso Quotes API

Ted Lasso Quotes CLI This cli makes it easy to get quotes from the Ted Lasso Quotes API Just clone the repo and build the binary for your distribution

Fredrik 6 Jun 15, 2022
Simple cli that makes your thoughts captured in the moment.

note Simple cli that makes your thoughts captured in the moment. Install go install github.com/jnszkr/note Usage > note This is my first note that I

Oszkár Jóna 4 Jan 8, 2022
a work time management CLI tool for any platform

english |日本語 jobgosh | job management tool made with golang for shell a multi-platform work time management CLI tool to track and improve your day to

奥田 龍馬 10 May 16, 2022
Another Go shellcode loader designed to work with Cobalt Strike raw binary payload.

Bankai Another Go shellcode loader designed to work with Cobalt Strike raw binary payload. I created this project to mainly educate myself learning Go

bigb0ss 123 Dec 29, 2022
Easily manage your work via command line

Wo Easily manage your work via command line Introduction Wo, is cli that provides it easy to manage your workspace. Wo provides to manipulating workfl

Ali Furkan 5 Dec 11, 2021
This package to make it easy to work with env

Go Env This package to make it easy to work with env Example usage package main

Sergey A. 3 Jan 30, 2022
A CLI tool for working with CloudWatch logs. It performs functions that I need at work.

CloudWatch Logs Utility A simple utility for working with CloudWatch Logs. AWS should probably build this themselves, but since they won't, I am here

J. Alexander Curtis 0 Dec 31, 2021