tmux-tilit

Better tiling for tmux 🪟🪓

tmux-tilit screenshot

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

Prefix Bindings

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

Keybinding	Action
H/J/K/L	Resize pane in direction
r	Reload config

Default prefix key is Ctrl + b

Copy Mode Bindings

Enable copy mode by pressing Alt + y:

This mode supports vi navigation keys by default

Keybinding	Action
y	Copy
Ctrl + v	Toggle block/rectangle mode
v	Start selection
V	Line selection

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:

set -g @tilit-config "$HOME/.config/tmux/tmux.conf"

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
Alt + ←/↓/↑/→	Focus pane in direction
Alt + Shift + ←/↓/↑/→	Move pane in direction
Alt + h/j/k/l	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:

# Default
set -g @tilit-mod 'M-'

# Example: Ctrl-based bindings
set -g @tilit-mod 'C-'

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

navigator for integrating with vim/neovim

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

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

set -g @tilit-navigator 'on'

This will let you seamlessly navigate between vim/neovim splits and tmux panes with Ctrl + hjkl.

prefix for integrating with window managers

If your window manager uses Alt as default modifier, it's recommended to switch to Super or Meta for a smoother experience.

If you do not want to do that you can enable prefix mode for tmux-tilit:

set -g @tilit-prefix 'C-space' # or any other key combo
set -g repeat-time 1000

This will let you hit Ctrl + space 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.

Challenges faced

Making sure the keybindings work across different command line programs and environments was challenging.

What I learned

• Learned more about the tmux API.

What's next

You tell me!

Hit the ⭐ button if you found this useful.

🧰 Tooling

• dots2k — Dev Environment
• nvim2k — Personalized Editor
• sway2k — Desktop Environment
• qute2k — Personalized Browser

🔍 More Info

• tmux-tea — Simple and powerful tmux session manager
• tmux2k — Makes your tmux statusbar pretty!

Source | Website