Agent skill

zellij-config

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/zellij-config

SKILL.md

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:

bash
# 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:

kdl
// 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:

kdl
layout {
    // Single pane
    pane

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

Common layout patterns:

Development layout (code + terminal):

kdl
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:

kdl
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:

kdl
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:

kdl
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:

kdl
// In config.kdl
theme "custom_theme"

Or via command line:

bash
zellij options --theme custom_theme

Keybindings (in config.kdl)

Keybinding structure:

kdl
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):

    bash
    Read ~/.config/zellij/config.kdl

  2. For new configs, generate base:

    bash
    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

kdl
// 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

kdl
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

kdl
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:
    bash
    ln -sf ~/Development/dotfiles/config/zellij ~/.config/zellij
  5. Update link-config.sh 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:

Useful commands:

bash
# Check config paths
zellij setup --check

# Generate default config
zellij setup --dump-config

# List available actions
zellij action --help

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results