Installing Zellij

Zellij is a modern terminal workspace and multiplexer written in Rust. It's designed as a tmux alternative with a focus on beginner-friendliness, out-of-the-box usability, and powerful features like floating panes, session management, and a WebAssembly plugin system.

What Zellij Provides

• Terminal multiplexing: Multiple panes, tabs, and sessions in one terminal
• Beautiful UI: Built-in status bar and tab bar (implemented as WASM plugins)
• Beginner-friendly: Keybinding hints always visible, intuitive defaults
• Floating panes: Modern window-manager-style pane overlays
• Layouts: Define and save custom workspace configurations
• Plugin system: Extend functionality with WebAssembly plugins (Rust or other languages)
• Session management: Attach/detach from sessions, session resurrection
• No configuration required: Works great out of the box

Zellij vs tmux

Key difference: Zellij prioritizes discoverability - you can be productive immediately without memorizing keybindings or writing config files.

Pre-Installation Checklist

✅ Homebrew installed (macOS package manager) ✅ Ghostty terminal (for optimal rendering and true color support) ✅ Nerd Font installed (for icons in Zellij's UI) ✅ No tmux auto-start (Zellij replaces tmux, they shouldn't run together)

Installation Steps

Step 1: Install Zellij via Homebrew

bash
# Install Zellij
brew install zellij

# Verify installation
zellij --version

You should see the version number (e.g., zellij 0.40.0).

Step 2: Install a Nerd Font (If Not Already Installed)

Zellij's UI uses icons that require a patched font:

bash
# Install JetBrainsMono Nerd Font (recommended)
brew install --cask font-jetbrains-mono-nerd-font

Configure Ghostty to use the Nerd Font:

Edit your Ghostty config:

bash
chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"

Add or update:

font-family = "JetBrainsMono Nerd Font"
font-size = 13

Apply changes:

bash
chezmoi apply

Restart Ghostty.

Step 3: First Launch

Start Zellij for the first time:

bash
zellij

You'll see:

• Tab bar at the top showing your current tab
• Status bar at the bottom showing available keybindings
• Welcome message in the main pane

The status bar shows context-sensitive keybindings - press Ctrl+p to enter "Pane mode" and see pane management shortcuts.

Step 4: Test Basic Functionality

Try these actions to verify everything works:

1. Split horizontally: Press Alt+n (creates pane below)
2. Split vertically: Press Alt+N (Shift+Alt+n, creates pane to the right)
3. Navigate panes: Press Alt+h/j/k/l (Vim-style navigation)
4. Create new tab: Press Ctrl+t then n
5. Rename tab: Press Ctrl+t then r, type name, press Enter
6. Quit Zellij: Press Ctrl+q (or type exit in all panes)

Step 5: Update Brewfile

Add Zellij to your managed Homebrew packages:

bash
# Regenerate Brewfile
brew bundle dump --file=~/Brewfile --force

# Add to chezmoi
chezmoi add ~/Brewfile

# Commit changes
cd ~/.local/share/chezmoi
git add Brewfile
git commit -m "Add zellij terminal multiplexer"
git push

See Managing Homebrew with Brewfile for full workflow details.

Integrating with Ghostty

Auto-Start Zellij on Ghostty Launch

Option 1: Launch Zellij manually when needed

The simplest approach - just run zellij when you want a multiplexed session:

bash
zellij

Or attach to an existing session:

bash
zellij attach session-name

Option 2: Auto-start Zellij in specific Ghostty windows

Configure Ghostty to launch Zellij for specific keybindings:

Edit Ghostty config:

bash
chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"

Add custom keybindings:

# Launch new window with Zellij
keybind = ctrl+shift+z=new_window:zellij

# Or make it the default for new windows
# window-shell-integration = false
# command = zellij

Option 3: Auto-start via shell rc file

Add to your ~/.zshrc:

bash
# Auto-start Zellij if not already in a session
if command -v zellij &> /dev/null && [ -z "$ZELLIJ" ]; then
  zellij
fi

Recommended approach for transitioning from tmux: Start with Option 1 (manual launch) while learning Zellij. Once comfortable, switch to Option 3 for auto-start.

Disable tmux Auto-Start

If you currently auto-start tmux in your shell rc file, comment it out:

Edit your shell config:

bash
chezmoi edit ~/.zshrc

Find and comment out tmux auto-start:

bash
# OLD tmux auto-start (disabled for Zellij)
# if command -v tmux &> /dev/null && [ -z "$TMUX" ]; then
#   tmux attach -t default || tmux new -s default
# fi

Apply changes:

bash
chezmoi apply
source ~/.zshrc

True Color and Font Rendering

Ghostty provides excellent support for Zellij:

• 24-bit true color: Automatic (no config needed)
• Font rendering: Optimized for coding fonts with Nerd Font icons
• Clipboard integration: Cmd+C/Cmd+V work seamlessly
• Cursor shapes: Change based on mode (requires shell-integration = true in Ghostty)

Configuration

Zellij works great with zero configuration, but you can customize it.

Config File Location

Zellij's config lives at:

~/.config/zellij/config.kdl

Create it if it doesn't exist:

bash
mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

The config uses KDL (pronounced "cuddle"), a document language similar to JSON/YAML but more human-friendly.

Essential Configuration Options

Edit ~/.config/zellij/config.kdl:

kdl
// Set default shell
default_shell "zsh"

// Simplified UI (hide tab bar if only one tab)
simplified_ui true

// Set theme
theme "catppuccin-mocha"

// Mouse mode
mouse_mode true

// Pane frames (borders around panes)
pane_frames true

// Copy on selection (like tmux)
copy_on_select true

// Scrollback buffer size
scrollback_editor "nvim"

Managing Themes

Zellij includes several built-in themes. View available themes:

bash
# List all themes
ls ~/.config/zellij/themes/

# Or check the default themes in the config dump
zellij setup --dump-config | grep -A 20 "themes"

Popular themes:

• catppuccin-mocha (dark, pastel)
• tokyo-night (dark, vibrant)
• gruvbox-dark (retro, warm)
• nord (cool blues)
• dracula (purple accents)

Set theme in config.kdl:

kdl
theme "catppuccin-mocha"

Custom Keybindings

Zellij uses modes (similar to vim) for keybindings. You can customize any binding:

kdl
keybinds {
    normal {
        // Add custom keybinding in normal mode
        bind "Ctrl g" { SwitchToMode "locked"; }
    }
    
    pane {
        // Customize pane mode keybindings
        bind "x" { CloseFocus; SwitchToMode "normal"; }
    }
}

Modes:

• normal - Default mode (navigation, tabs)
• pane - Pane management (Ctrl+p to enter)
• tab - Tab management (Ctrl+t to enter)
• resize - Resize panes (Ctrl+n to enter)
• move - Move panes (Ctrl+h to enter)
• scroll - Scrollback mode (Ctrl+s to enter)
• locked - Disable all Zellij keybindings (Ctrl+g to enter/exit)

Managing Config with chezmoi

Since Zellij config is important, track it with chezmoi:

bash
# Add Zellij config to chezmoi
chezmoi add ~/.config/zellij/config.kdl

# Edit via chezmoi
chezmoi edit ~/.config/zellij/config.kdl

# Apply changes
chezmoi apply

# Commit to version control
cd ~/.local/share/chezmoi
git add dot_config/zellij/config.kdl
git commit -m "Add Zellij configuration"
git push

See chezmoi for full dotfile management workflow.

Working with Layouts

Layouts are Zellij's way of defining custom workspace configurations (like tmux sessions with pre-defined panes).

Default Layouts Location

~/.config/zellij/layouts/

Creating a Layout

Create a layout file ~/.config/zellij/layouts/dev.kdl:

kdl
layout {
    // Define a tab for editing
    tab name="Editor" {
        pane split_direction="vertical" {
            pane {
                // Full-height editor pane
            }
            pane split_direction="horizontal" size="30%" {
                pane {
                    // Top-right terminal
                }
                pane {
                    // Bottom-right terminal
                }
            }
        }
    }
    
    // Define a tab for servers
    tab name="Servers" {
        pane {
            command "npm"
            args "run" "dev"
        }
    }
}

Using a Layout

Start Zellij with a specific layout:

bash
zellij --layout dev

Or switch to a layout in a running session:

bash
# Press Ctrl+p then 'l' to load a layout

Example Layouts

Three-column layout:

kdl
layout {
    tab {
        pane split_direction="vertical" {
            pane size="33%"
            pane size="34%"
            pane size="33%"
        }
    }
}

Editor + terminal + server:

kdl
layout {
    tab name="Dev" {
        pane split_direction="vertical" {
            pane command="nvim"
            pane split_direction="horizontal" size="40%" {
                pane // Terminal
                pane command="npm" args="run" "dev"
            }
        }
    }
}

Plugin System

Zellij has a WebAssembly (WASM) plugin system - plugins are compiled to WASM and run safely in Zellij's environment.

How Plugins Work

• Built-in UI components are plugins: The tab bar and status bar are Rust plugins
• Plugins are first-class citizens: They can render UI, react to state changes, and control Zellij
• Written in Rust (or any language that compiles to WASM)
• No separate plugin manager needed - configure plugins directly in config or layouts

Finding Plugins

Browse community plugins:

• awesome-zellij: https://github.com/zellij-org/awesome-zellij↗
• Official examples: https://zellij.dev/documentation/plugin-examples↗

Popular plugins:

• zjstatus - Customizable status bar with widgets
• zellij-forgot - Quick access to keybinding cheatsheet
• room - Session manager with quick switching
• zellij-sessionizer - fzf-based session creation from directories

Installing a Plugin

Unlike tmux's TPM, Zellij plugins are configured directly in config.kdl or layouts.

Example: Install zjstatus (custom status bar)

1. Download the plugin WASM file:

bash
mkdir -p ~/.config/zellij/plugins
cd ~/.config/zellij/plugins
curl -L https://github.com/dj95/zjstatus/releases/latest/download/zjstatus.wasm -o zjstatus.wasm

2. Configure it in ~/.config/zellij/config.kdl:

kdl
plugins {
    zjstatus location="file:~/.config/zellij/plugins/zjstatus.wasm" {
        format_left  "{mode} {tabs}"
        format_right "{datetime}"
        
        mode_normal "NORMAL"
        mode_locked "LOCKED"
        
        datetime        "#[fg=#6C7086,bold] {format} "
        datetime_format "%Y-%m-%d %H:%M"
    }
}

3. Use it in a layout:

kdl
layout {
    default_tab_template {
        pane
        pane size=1 borderless=true {
            plugin location="zjstatus"
        }
    }
}

Plugin Configuration in Layouts

Load plugins in specific panes:

kdl
layout {
    tab {
        pane
        pane size=1 borderless=true {
            plugin location="file:~/.config/zellij/plugins/zjstatus.wasm"
        }
    }
}

No TPM equivalent needed - plugins are just files you reference in configs/layouts.

Essential Keybindings

Zellij displays keybindings in the status bar. Here are the most common:

Normal Mode (Default)

Pane Mode (Ctrl+p)

Tab Mode (Ctrl+t)

Session Mode (Ctrl+o)

Pro tip: The status bar always shows available keybindings for your current mode. You never need to memorize everything!

Session Management

Zellij sessions persist in the background when you detach.

Creating Named Sessions

bash
# Create new session
zellij -s project-name

# Or
zellij --session project-name

Listing Sessions

bash
zellij list-sessions

# Or from within Zellij: Ctrl+o then 'w'

Attaching to Sessions

bash
# Attach to specific session
zellij attach project-name

# Attach to most recent session
zellij attach

Deleting Sessions

bash
zellij delete-session project-name

# Delete all sessions
zellij delete-all-sessions

Session Resurrection

Unlike tmux, Zellij automatically saves session state. If Zellij crashes or your computer restarts, sessions can be restored:

bash
# Zellij will prompt you to restore crashed sessions on next launch
zellij attach

Troubleshooting

Icons Not Displaying

Problem: Boxes or question marks instead of icons in the UI.

Solution:

1. Verify Nerd Font is installed: brew list | grep font
2. Check Ghostty config has the font: chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"
3. Ensure font-family = "JetBrainsMono Nerd Font"
4. Restart Ghostty

Keybindings Not Working

Problem: Alt/Ctrl keybindings don't respond.

Solution:

1. Check if you're in Locked mode (Ctrl+g toggles this)
2. Verify Ghostty isn't capturing the keybindings
3. Try different keybinding modes (Ctrl+p, Ctrl+t, etc.)

Zellij and tmux Conflict

Problem: Running both Zellij and tmux causes weird behavior.

Solution: Choose one multiplexer:

• If using Zellij: Disable tmux auto-start in ~/.zshrc
• If using tmux: Don't launch Zellij inside tmux (or vice versa)

Performance Issues

Problem: Zellij feels sluggish with many panes.

Solution:

1. Reduce scrollback buffer: Edit config.kdl → scrollback_editor settings
2. Disable mouse mode if not needed: mouse_mode false
3. Close unused panes/tabs
4. Check if a pane is running a resource-intensive process (htop, etc.)

Copy/Paste Not Working

Problem: Can't copy text from Zellij panes.

Solution:

1. Enter Scroll mode: Ctrl+s
2. Use mouse to select text (if mouse_mode true)
3. Text is automatically copied to system clipboard
4. Paste with Cmd+V (macOS) or Ctrl+Shift+V

Alternatively, configure copy_on_select true in config.kdl for automatic copying.

Migrating from tmux

If you're switching from tmux, here's a comparison:

Key workflow differences:

• tmux: Prefix key (Ctrl+b) before every command
• Zellij: Modal system (enter mode, then single keys) OR Alt-based shortcuts

Layouts vs Sessions:

• tmux sessions: Defined via commands or tmuxinator/tmuxp
• Zellij layouts: KDL files in ~/.config/zellij/layouts/

Next Steps

1. Learn the basics: Use Zellij daily for a week to internalize keybindings
2. Create a layout: Define a custom workspace for your most common project
3. Try plugins: Install zjstatus or zellij-sessionizer to enhance your workflow
4. Customize config: Tweak themes, keybindings, and UI settings in config.kdl
5. Version control: Add Zellij config to chezmoi for portability
6. Explore advanced features: Floating panes, session manager, plugin development

Links

Zellij Official Documentation

• URL: https://zellij.dev/documentation/↗
• Summary: Complete documentation covering installation, usage, layouts, plugins, and configuration in KDL format.
• Related: tmux Basics, Ghostty + tmux Startup Automation, chezmoi

awesome-zellij Plugin Repository

• URL: https://github.com/zellij-org/awesome-zellij↗
• Summary: Community-curated list of Zellij plugins, themes, and resources. Browse WASM plugins for status bars, session management, and integrations.
• Related: TPM - Tmux Plugin Manager

Zellij Plugin System Documentation

• URL: https://zellij.dev/documentation/plugins↗
• Summary: Guide to writing and using WebAssembly plugins for Zellij in Rust or other WASM-compatible languages.
• Related: Rust

KDL Configuration Language

• URL: https://kdl.dev/↗
• Summary: Documentation for KDL (pronounced "cuddle"), the human-friendly document language used for Zellij config files.
• Related: chezmoi