Topics

#cli #linux #plugin #tiling #tmux #utility #wm

Language breakdown

Shell 100.0%

▸ Files click to expand

README

tmux-tilit

Better tiling for tmux 🪟🪓

What is this

tmux-tilit brings tiling window manager features and intuitive keybindings to your tmux workflows, boosting your productivity like never before.

Features

Intuitive Tiling Management: Split and arrange panes, layouts, workspaces with intuitive keybindings similar to tiling window managers
Vim/Neovim Integration: Seamless navigation between vim/neovim splits and tmux panes with Navigator support
External Tools: Integration with utilities like lazygit, extrakto for text grabbing and tdo for notes management
Session Management: Integration with tea for session management
Prefix Mode: Optional prefix mode for compatibility with window managers that use Alt as default modifier
International Keyboard Support: Configurable shift+number mappings for different keyboard layouts

Prerequisites

Before you begin, ensure you have met the following requirements:

You have installed the latest version of tmux (>= 3.0) and tpm.

Installing tmux-tilit

To get tmux-tilit, add the following to your tmux.conf:

set -g @plugin '2kabhishek/tmux-tilit'

Using tmux-tilit

Keybindings

Alt is the default tilit-mod key, these bindings will change if you are changing it or using tilit-prefix.

| Keybinding | Action | | ---------------------------------------- | ------------------------ | | Alt + </kbd> | Last active window | | <kbd>Alt</kbd> + <kbd>,</kbd> | Rename current window | | <kbd>Alt</kbd> + <kbd>/</kbd> | Horizontal Split | | <kbd>Alt</kbd> + <kbd>\\</kbd> | Vertical Split | | <kbd>Alt</kbd> + <kbd>[ / ]</kbd> | Focus prev/next window | | <kbd>Alt</kbd> + <kbd>- / =</kbd> | Increase/Decrease width | | <kbd>Alt</kbd> + <kbd>Enter</kbd> | Create a new pane | | <kbd>Alt</kbd> + <kbd>0-9</kbd> | Switch to window 0-9 | | <kbd>Alt</kbd> + <kbd>Shift + 0-9</kbd> | Move pane to window 0-9 | | <kbd>Alt</kbd> + <kbd>Arrow Keys</kbd> | Resize pane in direction | | <kbd>Alt</kbd> + <kbd>h/j/k/l</kbd> | Focus pane in direction | | <kbd>Alt</kbd> + <kbd>H/J/K/L</kbd> | Move pane in direction | | <kbd>Alt</kbd> + <kbd>a</kbd> | Command mode | | <kbd>Alt</kbd> + <kbd>A</kbd> | Opencode CLI | | <kbd>Alt</kbd> + <kbd>b</kbd> | Toggle status bar | | <kbd>Alt</kbd> + <kbd>c</kbd> | Edit config | | <kbd>Alt</kbd> + <kbd>C</kbd> | Customize mode | | <kbd>Alt</kbd> + <kbd>d</kbd> | Run launcher, [dexe][3] | | <kbd>Alt</kbd> + <kbd>D</kbd> | Detach | | <kbd>Alt</kbd> + <kbd>e</kbd> | Layout: Even Vertical | | <kbd>Alt</kbd> + <kbd>E</kbd> | Layout: Even Horizontal | | <kbd>Alt</kbd> + <kbd>f</kbd> | Text grab [extrakto][2] | | <kbd>Alt</kbd> + <kbd>F</kbd> | Fuzzy edit files | | <kbd>Alt</kbd> + <kbd>g</kbd> | Open lazygit | | <kbd>Alt</kbd> + <kbd>i</kbd> | Synchronize pane inputs | | <kbd>Alt</kbd> + <kbd>I</kbd> | Open tilit README | | <kbd>Alt</kbd> + <kbd>m</kbd> | Layout: Main Vertical | | <kbd>Alt</kbd> + <kbd>M</kbd> | Layout: Main Horizontal | | <kbd>Alt</kbd> + <kbd>n</kbd> | Pending todos [tdo][1] | | <kbd>Alt</kbd> + <kbd>N</kbd> | Search notes [tdo][1] | | <kbd>Alt</kbd> + <kbd>o</kbd> | Open floating terminal | | <kbd>Alt</kbd> + <kbd>p</kbd> | Last active pane | | <kbd>Alt</kbd> + <kbd>q</kbd> | Close session | | <kbd>Alt</kbd> + <kbd>r</kbd> | Reload config | | <kbd>Alt</kbd> + <kbd>R</kbd> | Rotate window | | <kbd>Alt</kbd> + <kbd>s</kbd> | Show all panes | | <kbd>Alt</kbd> + <kbd>t</kbd> | Session manager [tea][1] | | <kbd>Alt</kbd> + <kbd>T</kbd> | Layout: Tiled | | <kbd>Alt</kbd> + <kbd>w</kbd> | Move pane to new window | | <kbd>Alt</kbd> + <kbd>x</kbd> | Close pane | | <kbd>Alt</kbd> + <kbd>X</kbd> | Close window | | <kbd>Alt</kbd> + <kbd>y</kbd> | Toggle copy mode | | <kbd>Alt</kbd> + <kbd>z</kbd> | Layout: Zoom | | <kbd>Shift</kbd> + <kbd>Left/Right</kbd> | Focus prev/next window |


Prefix Bindings

tmux-tilit sets up keybindings that work with the tmux prefix key:


| Keybinding         | Action                   | | ------------------ | ------------------------ | | <kbd>H/J/K/L</kbd> | Resize pane in direction | | <kbd>r</kbd>       | Reload config            |

> Default prefix key is <kbd>Ctrl</kbd> + <kbd>b</kbd>


Copy Mode Bindings
Enable/Disable copy mode by pressing <kbd>Alt</kbd> + <kbd>y</kbd>:
> This mode supports vi navigation keys by default
| Keybinding                     | Action                      | | ------------------------------ | --------------------------- | | <kbd>Alt</kbd> + <kbd>y</kbd>  | Toggle/Exit copy mode       | | <kbd>y</kbd>                   | Copy                        | | <kbd>Ctrl</kbd> + <kbd>v</kbd> | Toggle block/rectangle mode | | <kbd>v</kbd>                   | Start selection             | | <kbd>V</kbd>                   | Line selection              |
[1]: https://github.com/2KAbhishek/tdo [2]: https://github.com/laktak/extrakto [3]: https://github.com/2KAbhishek/dexe [4]: https://github.com/2KAbhishek/tmux-tea
Customizing tmux-tilit

config `for custom tmux config location`

By default, tmux-tilit uses $HOME/.tmux.conf for config-related operations (reload, edit).


If your config is in a different location, you can set:
<pre><code class="lang-bash">set -g @tilit-config &quot;$HOME/.config/tmux/tmux.conf&quot;</code></pre>

autotiling `for dynamic layout splits`

By default, autotiling is enabled ('on'). This automatically splits panes horizontally or vertically based on active pane dimensions (similar to i3/sway autotiling).


To disable this behavior:
<pre><code class="lang-bash">set -g @tilit-autotiling &#39;off&#39;</code></pre>

You can customize the aspect ratio threshold (default is 2.0). Lower values trigger horizontal splits more easily:


<pre><code class="lang-bash">set -g @tilit-splitratio &#39;1.7&#39;</code></pre>

> Note: For the best autotiling experience, it is recommended to unset @tilit-layout (or leave it empty) so that tmux does not force a specific static layout after splitting.

easymode `for arrow key navigation`

To navigate using arrow keys, you can enable easy mode with: set -g @tilit-easymode 'on'


The revised keybindings for the pane focus and movement then become:
| Keybinding                                                          | Description              | | ------------------------------------------------------------------- | ------------------------ | | <kbd>Alt</kbd> + <kbd>&#8592;/&#8595;/&#8593;/&#8594;</kbd>         | Focus pane in direction  | | <kbd>Alt</kbd> + <kbd>Shift + &#8592;/&#8595;/&#8593;/&#8594;</kbd> | Move pane in direction   | | <kbd>Alt</kbd> + <kbd>h/j/k/l</kbd>                                 | Resize pane in direction |

layout `for customizing default layout`

You can set the default layout with set -g @tilit-default 'layout', this will be used when creating new windows or panes.


Available layouts are:

main-vertical

main-horizontal

tiled

even-vertical

even-horizontal

mod `for customizing the modifier key`

By default, tmux-tilit uses M- (Alt/Meta) as the modifier for direct keybindings.


You can change it to another tmux modifier prefix:
<pre><code class="lang-bash"># Default set -g @tilit-mod &#39;M-&#39;
Example: Ctrl-based bindings
set -g @tilit-mod &#39;C-&#39;</code></pre>

@tilit-mod is used only in non-prefix mode.

navigator `for integrating with vim/neovim`


To setup navigation with neovim install [Navigator.nvim][4] and for vim use [vim-tmux-navigator][5]

Then, in your ~/.tmux.conf add:


<pre><code class="lang-bash">set -g @tilit-navigator &#39;on&#39;</code></pre>
This will let you seamlessly navigate between vim/neovim splits and tmux panes with <kbd>Ctrl</kbd> + <kbd>h</kbd><kbd>j</kbd><kbd>k</kbd><kbd>l</kbd>.
[4]: https://github.com/numToStr/Navigator.nvim [5]: https://github.com/christoomey/vim-tmux-navigator

prefix `for integrating with window managers`


If your window manager uses <kbd>Alt</kbd> as default modifier, it's recommended to switch to <kbd>Super</kbd> or <kbd>Meta</kbd> for a smoother experience.
If you do not want to do that you can enable prefix mode for tmux-tilit:
<pre><code class="lang-bash">set -g @tilit-prefix &#39;C-space&#39; # or any other key combo set -g repeat-time 1000</code></pre>
This will let you hit <kbd>Ctrl</kbd> + <kbd>space</kbd> and then a key to perform an action, repeat-time lets you run more actions with a single prefix.
> Note: This prefix is different from the tmux default prefix. > If you do not use C-a as your tmux prefix - I highly recommend using that as the tilit-prefix and set the tmux-prefix back to C-b

shiftnum `for working with international keyboards`

You can set the @tilit-shiftnum` option to match your keyboard layout:

# US Keyboard
set -g @tilit-shiftnum '!@#$%^&*()'
UK Keyboard
set -g @tilit-shiftnum '!"£$%^&*()'

How I built this

Major credits to tmux-tilish for the inspiration I wanted to add some new commands and integrations, make the keybindings match better with tmux defaults.