Zellij Config

Zellij Configuration

Configure Zellij terminal multiplexer following best practices and XDG Base Directory specification.

Config File Locations

Zellij uses KDL (KDL Document Language) format and follows XDG spec:

• Primary config: ~/.config/zellij/config.kdl
• Themes: ~/.config/zellij/themes/
• Layouts: ~/.config/zellij/layouts/

Instructions

1. Identify Configuration Need

Determine what the user wants to configure:

• Initial setup: Create base config with sensible defaults
• Layouts: Pane/tab arrangements for workflows
• Themes: Colors and appearance customization
• Keybindings: Custom shortcuts and mode bindings
• Behavior: General settings, mouse, copy-paste

2. Configuration Initialization

For new setup:

# Generate default config
mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

# Check config directory location
zellij setup --check

3. Configuration Categories

General Settings (config.kdl)

Basic structure:

// Mouse support
mouse_mode true

// Pane frames
pane_frames true

// Copy on selection
copy_on_select true

// Scrollback
scroll_buffer_size 10000

// Default shell
default_shell "fish"

// Default layout
default_layout "compact"

// Default theme
theme "catppuccin-mocha"

// UI configuration
simplified_ui false
default_mode "normal"

// Session serialization
session_serialization true

// Clipboard provider
copy_command "pbcopy"  // macOS
// copy_command "xclip -selection clipboard"  // Linux X11
// copy_command "wl-copy"  // Linux Wayland

Important settings:

• mouse_mode: Enable/disable mouse support
• pane_frames: Show borders around panes
• copy_on_select: Auto-copy selected text
• scroll_buffer_size: Lines of scrollback history
• default_shell: Shell to launch in new panes
• session_serialization: Save/restore sessions on exit
• mirror_session: Allow session mirroring

Layouts (*.kdl in layouts/)

Basic layout structure:

layout {
    // Single pane
    pane

    // Vertical split with two panes
    pane split_direction="vertical" {
        pane
        pane
    }
}

Common layout patterns:

Development layout (code + terminal):

layout {
    default_tab_template {
        pane size=1 borderless=true {
            plugin location="zellij:tab-bar"
        }
        children
        pane size=2 borderless=true {
            plugin location="zellij:status-bar"
        }
    }

    tab name="dev" {
        pane split_direction="vertical" {
            pane size="70%" {
                // Editor pane
            }
            pane split_direction="horizontal" {
                pane {
                    // Terminal for commands
                }
                pane {
                    // Logs or tests
                }
            }
        }
    }
}

Multi-tab workspace:

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

    tab name="servers" {
        pane split_direction="vertical" {
            pane command="npm" {
                args "run" "dev"
            }
            pane command="docker" {
                args "compose" "logs" "-f"
            }
        }
    }

    tab name="monitoring" {
        pane command="htop"
        pane command="btop"
    }
}

Pane properties:

• split_direction: "vertical" or "horizontal"
• size: Percentage ("70%") or fixed
• command: Executable to run
• args: Command arguments (space-separated strings)
• cwd: Working directory
• focus: Boolean for initial focus
• borderless: Hide pane borders
• name: Pane title

Layout best practices:

• Use default_tab_template for consistent tab structure
• Include tab-bar and status-bar plugins for UI
• Name tabs descriptively
• Set focus on primary working pane
• Use size percentages for responsive layouts

Themes (*.kdl in themes/)

Theme structure:

themes {
    custom_theme {
        fg "#cdd6f4"
        bg "#1e1e2e"
        black "#45475a"
        red "#f38ba8"
        green "#a6e3a1"
        yellow "#f9e2af"
        blue "#89b4fa"
        magenta "#f5c2e7"
        cyan "#94e2d5"
        white "#bac2de"
        orange "#fab387"
    }
}

Color properties (all RGB or hex):

• fg: Foreground text
• bg: Background
• black, red, green, yellow, blue, magenta, cyan, white: ANSI colors
• orange: Additional accent color

UI component theming:

themes {
    detailed_theme {
        // Base colors
        fg "#cdd6f4"
        bg "#1e1e2e"

        // ANSI colors
        black "#45475a"
        red "#f38ba8"
        green "#a6e3a1"
        yellow "#f9e2af"
        blue "#89b4fa"
        magenta "#f5c2e7"
        cyan "#94e2d5"
        white "#bac2de"
        orange "#fab387"

        // Frame colors
        text_unselected {
            base 255 255 255
            background 30 30 46
        }

        text_selected {
            base 49 50 68
            background 205 214 244
        }

        ribbon_unselected {
            base 255 255 255
            background 88 91 112
        }

        ribbon_selected {
            base 49 50 68
            background 137 180 250
        }

        frame_unselected {
            base 88 91 112
            background 30 30 46
        }

        frame_selected {
            base 137 180 250
            background 30 30 46
        }
    }
}

Built-in themes to reference:

• catppuccin-mocha, catppuccin-latte
• dracula
• gruvbox-dark, gruvbox-light
• nord
• tokyo-night, tokyo-night-storm

Apply theme:

// In config.kdl
theme "custom_theme"

Or via command line:

zellij options --theme custom_theme

Keybindings (in config.kdl)

Keybinding structure:

keybinds {
    normal {
        bind "Ctrl g" { SwitchToMode "locked"; }
        bind "Ctrl p" { SwitchToMode "pane"; }
        bind "Ctrl t" { SwitchToMode "tab"; }
        bind "Ctrl n" { SwitchToMode "resize"; }
        bind "Ctrl h" { MoveFocus "Left"; }
        bind "Ctrl l" { MoveFocus "Right"; }
        bind "Ctrl j" { MoveFocus "Down"; }
        bind "Ctrl k" { MoveFocus "Up"; }
    }

    pane {
        bind "Ctrl p" { SwitchToMode "normal"; }
        bind "h" { MoveFocus "Left"; }
        bind "l" { MoveFocus "Right"; }
        bind "j" { MoveFocus "Down"; }
        bind "k" { MoveFocus "Up"; }
        bind "n" { NewPane; SwitchToMode "normal"; }
        bind "d" { NewPane "Down"; SwitchToMode "normal"; }
        bind "r" { NewPane "Right"; SwitchToMode "normal"; }
        bind "x" { CloseFocus; SwitchToMode "normal"; }
        bind "f" { ToggleFocusFullscreen; SwitchToMode "normal"; }
    }

    tab {
        bind "Ctrl t" { SwitchToMode "normal"; }
        bind "n" { NewTab; SwitchToMode "normal"; }
        bind "x" { CloseTab; SwitchToMode "normal"; }
        bind "r" { SwitchToMode "renametab"; }
        bind "h" { GoToPreviousTab; }
        bind "l" { GoToNextTab; }
        bind "1" { GoToTab 1; SwitchToMode "normal"; }
        bind "2" { GoToTab 2; SwitchToMode "normal"; }
        bind "3" { GoToTab 3; SwitchToMode "normal"; }
    }

    resize {
        bind "Ctrl n" { SwitchToMode "normal"; }
        bind "h" { Resize "Left"; }
        bind "j" { Resize "Down"; }
        bind "k" { Resize "Up"; }
        bind "l" { Resize "Right"; }
        bind "=" { Resize "Increase"; }
        bind "-" { Resize "Decrease"; }
    }

    locked {
        bind "Ctrl g" { SwitchToMode "normal"; }
    }
}

Available modes:

• normal: Default mode
• pane: Pane management
• tab: Tab management
• resize: Pane resizing
• move: Moving panes
• scroll: Scrollback navigation
• locked: Input pass-through (all keys go to terminal)
• renametab, renamepane: Renaming modes
• session: Session management

Common actions:

• SwitchToMode "mode": Change mode
• MoveFocus "direction": Focus navigation (Left/Right/Up/Down)
• NewPane, NewPane "direction": Create pane
• CloseFocus: Close focused pane
• NewTab, CloseTab: Tab management
• GoToTab N: Jump to tab number
• GoToPreviousTab, GoToNextTab: Tab navigation
• Resize "direction": Resize panes
• ToggleFocusFullscreen: Maximize/restore pane
• TogglePaneFrames: Show/hide borders
• Quit: Exit Zellij

Key syntax:

• "Ctrl x": Control + key
• "Alt x": Alt + key
• "Ctrl Alt x": Multiple modifiers
• "F1" through "F12": Function keys
• "Space", "Enter", "Tab", "Esc": Special keys
• Multiple bindings: bind "x" "X" { Action; }

4. Configuration Workflow

1. Read existing config (if present):

   Read ~/.config/zellij/config.kdl
   

2. For new configs, generate base:

   zellij setup --dump-config > ~/.config/zellij/config.kdl
   

3. Apply changes using Edit or Write:

   • Use Edit for incremental changes
   • Use Write for new files (layouts, themes)

4. Validate KDL syntax:

   • Proper nesting with braces {}
   • Quoted strings for keys and values
   • No trailing commas
   • Comments use //

5. Test changes:

   • Most config changes apply to new panes/tabs/sessions
   • Config file is live-reloaded
   • Use zellij setup --check to verify paths

5. Common Configuration Tasks

Complete Initial Setup

// Mouse and UI
mouse_mode true
pane_frames true
simplified_ui false

// Behavior
copy_on_select true
scroll_buffer_size 10000
session_serialization true

// Shell and theme
default_shell "fish"
theme "catppuccin-mocha"

// Clipboard (macOS)
copy_command "pbcopy"

Vim-Style Keybindings

keybinds {
    normal {
        bind "Ctrl h" { MoveFocus "Left"; }
        bind "Ctrl j" { MoveFocus "Down"; }
        bind "Ctrl k" { MoveFocus "Up"; }
        bind "Ctrl l" { MoveFocus "Right"; }

        bind "Ctrl n" { NewPane; }
        bind "Ctrl x" { CloseFocus; }
    }
}

Custom Development Layout

layout {
    tab name="dev" {
        pane split_direction="vertical" {
            pane size="60%"
            pane split_direction="horizontal" {
                pane command="npm" {
                    args "run" "dev"
                }
                pane
            }
        }
    }
}

6. Integration with Dotfiles

Since this is a dotfiles repo following XDG spec:

1. Store configs: config/zellij/config.kdl
2. Store layouts: config/zellij/layouts/*.kdl
3. Store themes: config/zellij/themes/*.kdl
4. Symlink to XDG location:

   ln -sf ~/Development/dotfiles/config/zellij ~/.config/zellij
   

5. Update src/dotfiles_setup/links.py to include Zellij
6. Add to flake.nix package list
7. Add to README in tools section

Output Format

When configuring Zellij:

1. Show changes clearly using KDL code blocks
2. Explain structure for complex layouts/themes
3. Provide test commands when relevant
4. Note live reload: "Config changes apply automatically"
5. Include file paths using file:line format

Project Context

This dotfiles repo:

• Uses Nix for package management (flake.nix)
• Symlinks configs from config/** to ~/.config/
• Follows XDG Base Directory spec
• Uses Fish shell by default
• Prioritizes reproducibility and cross-platform support

Reference Documentation

For comprehensive options, reference:

• Configuration: https://zellij.dev/documentation/configuration.html
• Keybindings: https://zellij.dev/documentation/keybindings.html
• Themes: https://zellij.dev/documentation/themes.html
• Layouts: https://zellij.dev/documentation/layouts.html

Useful commands:

# Check config paths
zellij setup --check

# Generate default config
zellij setup --dump-config

# List available actions
zellij action --help