Zellij Configuration - Gentleman.Dots

Overview

Zellij is a terminal workspace built with Rust, offering a modern alternative to Tmux. It features modal keybindings (similar to Vim), built-in session persistence, and a beautiful UI with discoverable features. The Gentleman.Dots configuration includes custom themes, layouts, and an innovative keybinding helper plugin.

Zellij uses a modal system with modes like locked, pane, tab, resize, etc. Press Ctrl+g to enter command mode, then a letter to switch modes.

Key Features

Modal Keybindings

Vim-like modes for different operations

Built-in Layouts

Pre-configured workspace layouts for different tasks

Auto Session Persistence

Sessions are automatically saved and can be restored

Zellij Forgot Plugin

Press Alt+y to see all keybindings

Installation

Install Zellij

cargo install zellij

You can also use Homebrew: brew install zellij

Copy Configuration

mkdir -p ~/.config/zellij
cp -r GentlemanZellij/zellij/* ~/.config/zellij/

Verify Installation

zellij --version

Start Zellij

zellij

Configuration Breakdown

Zellij uses a modal keybinding system. The default mode is locked, where most keys are passed through to your shell. Press Ctrl+g to unlock and enter command mode.

config.kdl

default_mode "locked"

Available modes:

locked - Normal terminal input (default)
pane - Pane management
tab - Tab management
resize - Resize panes
move - Move panes
scroll - Scroll mode
search - Search in scrollback
session - Session management

Themes

The configuration includes multiple beautiful themes:

config.kdl

themes {
    kanagawa_wave {
        fg "#DCD7BA"
        bg "#1F1F28"
        red "#C34043"
        green "#76946A"
        yellow "#C0A36E"
        blue "#7E9CD8"
        magenta "#957FB8"
        cyan "#6A9589"
        orange "#FFA066"
        black "#1F1F28"
        white "#DCD7BA"
    }
    
    kanagawa_dragon { ... }
    everforest { ... }
    rose_pine_moon { ... }
    sakura { ... }
    oldWorld { ... }
}

theme "kanagawa_wave"

To change themes, edit config.kdl and update the theme setting to one of: kanagawa_wave, kanagawa_dragon, everforest, rose_pine_moon, sakura, or oldWorld

Default Layout

The configuration uses a custom work layout:

config.kdl

default_layout "work_kanagawa"

Available layouts in ~/.config/zellij/layouts/:

work.kdl - Basic 2-tab setup (nvim + shell)
work_kanagawa.kdl - Kanagawa themed
work_everforest.kdl - Everforest themed
work_sakura.kdl - Sakura themed
work_oldWorld.kdl - OldWorld themed

Custom Plugins

Two WebAssembly plugins are included:

zjstatus.wasm - Custom status bar with git integration
zellij_forgot.wasm - Interactive keybinding helper

Zellij Forgot Plugin

Press Alt+y to launch the keybinding helper:

config.kdl

bind "Alt y" {
    LaunchOrFocusPlugin "file:~/.config/zellij/plugins/zellij_forgot.wasm" {
        "lock"                  "ctrl + g"
        "unlock"                "ctrl + g"
        "new pane"              "Alt + n || ctrl + g + p + n"
        "change focus of pane"  "Alt + arrow key || ctrl + g + p + arrow key"
        # ... more keybindings
        floating true
    }
}

Essential Keybindings

Mode Switching

Keybinding	Action
`Ctrl+g`	Toggle locked/unlocked mode
`Ctrl+q`	Quit Zellij
`Esc` or `Enter`	Return to locked mode
`p`	Switch to pane mode
`t`	Switch to tab mode
`r`	Switch to resize mode
`m`	Switch to move mode
`s`	Switch to scroll mode
`o`	Switch to session mode

Quick Actions (Work in Locked Mode)

Keybinding	Action
`Alt+n`	New pane
`Alt+h/j/k/l`	Navigate panes (Vim style)
`Alt+←/↓/↑/→`	Navigate panes (Arrow keys)
`Alt+f`	Toggle floating pane
`Alt+[`	Previous layout
`Alt+]`	Next layout
`Alt+i`	Move tab left
`Alt+o`	Move tab right
`Alt+y`	Show keybinding helper

Pane Mode (`Ctrl+g` then `p`)

Keybinding	Action
`n`	New pane
`r`	New pane on the right
`d`	New pane below
`x`	Close focused pane
`f`	Toggle fullscreen
`w`	Toggle floating panes
`e`	Toggle pane embed/float
`z`	Toggle pane frames
`h/j/k/l`	Move focus
`c`	Rename pane
`Tab`	Switch focus

Tab Mode (`Ctrl+g` then `t`)

Keybinding	Action
`n`	New tab
`x`	Close tab
`r`	Rename tab
`h/j/k/l`	Navigate tabs
`1-9`	Go to tab number
`s`	Toggle sync tab (send input to all panes)
`b`	Break pane to new tab
`[`	Break pane left
`]`	Break pane right
`Tab`	Toggle between tabs

Resize Mode (`Ctrl+g` then `r`)

Keybinding	Action
`h/j/k/l`	Increase size in direction
`H/J/K/L`	Decrease size in direction
`+` or `=`	Increase size
`-`	Decrease size
`←/↓/↑/→`	Increase size in direction

Scroll Mode (`Ctrl+g` then `s`)

Keybinding	Action
`j/k` or `↓/↑`	Scroll down/up
`h/l` or `←/→`	Page scroll
`d`	Half page down
`u`	Half page up
`Ctrl+f`	Page down
`Ctrl+b`	Page up
`Ctrl+c`	Scroll to bottom
`f`	Enter search mode
`e`	Edit scrollback in $EDITOR

Session Mode (`Ctrl+g` then `o`)

Keybinding	Action
`w`	Open session manager
`c`	Open configuration
`p`	Open plugin manager
`d`	Detach from session

Work Layout Breakdown

The default work.kdl layout creates a productive workspace:

work.kdl

layout {
    tab name="nvim" focus=true {
        pane
    }

    tab name="shell" {
        pane
    }

    default_tab_template {
        pane size=1 borderless=true {
            plugin location="file:~/.config/zellij/plugins/zjstatus.wasm" {
              format_left   "{mode} #[fg=#e0def4,bold]{session}{tabs}"
              format_right  "{command_git_branch} {datetime}"
              # Git branch indicator
              command_git_branch_command     "git rev-parse --abbrev-ref HEAD"
              command_git_branch_format      "#[fg=#3e8fb0] {stdout} "
              # Date and time
              datetime        "#[fg=#6e6a86,bold] {format} "
              datetime_format "%A, %d %b %Y %H:%M"
            }
        }
        children
        pane size=1 borderless=true  {
          plugin location="zellij:status-bar"
        }
    }
}

Features:

Two tabs: nvim (focused) and shell
Top status bar with git branch and date/time
Bottom status bar with mode indicator
Automatic git branch detection in the current directory

Advanced Usage

Creating Custom Layouts

Create a new layout file in ~/.config/zellij/layouts/:

my-layout.kdl

layout {
    tab name="code" {
        pane split_direction="vertical" {
            pane
            pane split_direction="horizontal" {
                pane
                pane
            }
        }
    }
    
    tab name="terminal" {
        pane
    }
}

Load it with:

zellij --layout my-layout

Session Management

List sessions:

zellij list-sessions
# or shorthand
zellij ls

Attach to session:

zellij attach <session-name>
# or shorthand
zellij a <session-name>

Create named session:

zellij --session my-project

Delete session:

zellij delete-session <session-name>

Session Persistence

Zellij automatically serializes sessions:

config.kdl

session_serialization true  # enabled by default

Sessions are saved to ~/.cache/zellij/ and can be restored after crashes or reboots.

Scrollback Editor

The configuration uses Neovim for editing scrollback:

config.kdl

scrollback_editor "nvim"

Press Ctrl+g → s → e to edit scrollback in Neovim.

Customization Tips

Change Theme

Edit config.kdl and update the theme setting:

config.kdl

theme "everforest"  # or kanagawa_dragon, rose_pine_moon, sakura, oldWorld

To use a matching layout:

config.kdl

default_layout "work_everforest"

Disable Mouse Mode

config.kdl

mouse_mode false

Change Default Shell

config.kdl

default_shell "fish"  # or zsh, nu, bash

Adjust Scroll Buffer

config.kdl

scroll_buffer_size 50000  # default is 10000

Simplified UI (No Nerd Fonts)

config.kdl

simplified_ui true

Troubleshooting

Zellij not found after installation

If you installed with cargo install, ensure ~/.cargo/bin is in your PATH:

echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
# or for Fish
fish_add_path ~/.cargo/bin

Then restart your shell.

Keybindings not working

Make sure you’re in the correct mode. Press Ctrl+g to unlock from locked mode first.If using a terminal that captures certain key combinations, check your terminal’s keybinding settings.

Themes not applying

Verify the theme name matches exactly (case-sensitive):

# Check available themes in config.kdl
grep -A 1 "^    [a-z_]* {" ~/.config/zellij/config.kdl

Then update the theme setting at the bottom of the file.

Status bar plugins not loading

Ensure the plugin files exist:

ls ~/.config/zellij/plugins/
# Should show: zjstatus.wasm, zellij_forgot.wasm

If missing, recopy from the Gentleman.Dots repository.

Git branch not showing in status bar

The git branch only shows when you’re in a git repository. Navigate to a git project directory.If still not working, ensure git is in your PATH:

which git

Shell Integration

Gentleman.Dots includes shell integration to auto-start Zellij.

Zsh Integration

Edit ~/.zshrc:

.zshrc

WM_VAR="$ZELLIJ"
WM_CMD="zellij"

if [ -z "$WM_VAR" ]; then
    $WM_CMD
fi

Fish Integration

Edit ~/.config/fish/config.fish:

config.fish

if not set -q ZELLIJ
    zellij
end

Nushell Integration

Edit Nushell config:

config.nu

let MULTIPLEXER = "zellij"
let MULTIPLEXER_ENV_PREFIX = "ZELLIJ"

if ($env | get -i $MULTIPLEXER_ENV_PREFIX | is-empty) {
    ^$MULTIPLEXER
}

Comparison with Tmux

Advantages

More intuitive UI out of the box
Modal keybindings (less RSI from prefix key)
Built-in session persistence
Better default layouts
Discoverable features (Alt+y for help)
Modern codebase (Rust)

Trade-offs

Smaller plugin ecosystem
Fewer third-party resources
Rust toolchain required for building
Different muscle memory if coming from Tmux

Resources

Zellij Website

Official documentation and guides

Zellij GitHub

Source code and issue tracker

Layout Gallery

Example layouts and templates

Plugin System

Build custom WebAssembly plugins

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Key Features

Modal Keybindings

Built-in Layouts

Auto Session Persistence

Zellij Forgot Plugin

​Installation

​Configuration Breakdown

​Modal System

​Themes

​Default Layout

​Custom Plugins

​Zellij Forgot Plugin

​Essential Keybindings

​Mode Switching

​Quick Actions (Work in Locked Mode)

​Pane Mode (Ctrl+g then p)

​Tab Mode (Ctrl+g then t)

​Resize Mode (Ctrl+g then r)

​Scroll Mode (Ctrl+g then s)

​Session Mode (Ctrl+g then o)

​Work Layout Breakdown

​Advanced Usage

​Creating Custom Layouts

​Session Management

​Session Persistence

​Scrollback Editor

​Customization Tips

​Change Theme

​Disable Mouse Mode

​Change Default Shell

​Adjust Scroll Buffer

​Simplified UI (No Nerd Fonts)

​Troubleshooting

​Shell Integration

​Zsh Integration

​Fish Integration

​Nushell Integration

​Comparison with Tmux

Advantages

Trade-offs

​Resources

Zellij Website

Zellij GitHub

Layout Gallery

Plugin System

Build docs developers (and LLMs) love

Overview

Key Features

Installation

Configuration Breakdown

Modal System

Themes

Default Layout

Custom Plugins

Zellij Forgot Plugin

Essential Keybindings

Mode Switching

Quick Actions (Work in Locked Mode)

Pane Mode (`Ctrl+g` then `p`)

Tab Mode (`Ctrl+g` then `t`)

Resize Mode (`Ctrl+g` then `r`)

Scroll Mode (`Ctrl+g` then `s`)

Session Mode (`Ctrl+g` then `o`)

Work Layout Breakdown

Advanced Usage

Creating Custom Layouts

Session Management

Session Persistence

Scrollback Editor

Customization Tips

Change Theme

Disable Mouse Mode

Change Default Shell

Adjust Scroll Buffer

Simplified UI (No Nerd Fonts)

Troubleshooting

Shell Integration

Zsh Integration

Fish Integration

Nushell Integration

Comparison with Tmux

Resources