zellij-config

name	zellij-config
description	Configure Zellij terminal multiplexer with layouts, themes, keybindings, and behavior settings using KDL format. Use when setting up Zellij, creating layouts, customizing themes, or configuring keybinds. Keywords: zellij, terminal multiplexer, layout, theme, keybind, KDL, config, tmux alternative, terminal workspace

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