zellij-guide

Zellij Guide — Personal Reference

Binary: /Users/wcygan/.nix-profile/bin/zellij (installed via Nix flake) Config: ~/Development/dotfiles/config/zellij/config.kdl → symlinked to ~/.config/zellij/config.kdl Layouts: ~/Development/dotfiles/config/zellij/layouts/

For exhaustive action/option/layout reference, see reference.md.

---

Quick Start

zellij                           # New session (random name)
zellij -s work                   # New named session
zellij -l dev                    # New session with dev.kdl layout
zellij ls                        # List sessions (including exited)
zellij a work                    # Attach to "work" session
zellij d work                    # Delete exited session

---

Your Keybinds (clear-defaults=true, vim-style)

Your config uses clear-defaults=true — only these bindings exist:

Normal Mode (default)

Pane Mode (Ctrl p to enter, Esc to exit)

Resize Mode (Ctrl r to enter, Esc to exit)

Move Mode (Ctrl m to enter, Esc to exit)

Scroll Mode (Ctrl b to enter, Esc to exit)

Locked Mode (Ctrl g to toggle)

All keys pass through to the terminal. Only Ctrl g exits.

Modes NOT configured (from defaults)

Your config does not define: tab, search, entersearch, renametab, renamepane, session, tmux. Consider adding search and session modes for search-in-scrollback and session manager access.

---

Your Config Summary

// Key settings in config.kdl:
default_layout "compact"          // 1-line compact-bar (tab + status combined)
pane_frames false                 // No borders between panes
theme "default"                   // Base16 dark theme (defined inline)
default_shell "~/.nix-profile/bin/fish"
copy_on_select true
scrollback_editor "/usr/bin/nvim"
session_serialization true        // Enable resurrection
serialize_pane_viewport true      // Save visible content
max_panes 100
layout_dir "~/.config/zellij/layouts"

Note: default_shell and layout_dir use /home/wcygan/ paths (Linux). On macOS these should be /Users/wcygan/ paths. Consider using $HOME or updating for cross-platform use.

---

Your Layouts

dev.kdl (3-tab development layout)

Tab "main" (focused):
┌─────────────────────┬──────────┐
│                     │ terminal │
│  editor (70%)       ├──────────┤
│                     │  logs    │
└─────────────────────┴──────────┘

Tab "git":     lazygit (full pane)
Tab "monitor": btop (50%) + services (50%)

Load with: zellij -l dev or zellij --layout ~/.config/zellij/layouts/dev.kdl

---

Modes Reference (13 total)

---

CLI Quick Reference

Session Management

zellij                                    # New session
zellij -s <name>                          # Named session
zellij ls                                 # List all (running + exited)
zellij attach <name>                      # Attach / resurrect
zellij attach -c <name>                   # Create-or-attach
zellij kill-session <name>                # Kill running session
zellij delete-session <name>              # Delete exited session
zellij kill-all-sessions                  # Kill all
zellij delete-all-sessions                # Delete all exited

Run Commands in Panes

zellij run -- htop                        # New pane running htop
zellij run -f -- htop                     # Floating pane
zellij run -f --width 80% --height 80% -- htop  # Sized floating
zellij run -i -- make build               # In-place (replaces current pane)
zellij run -c -- make test                # Close pane on exit
zellij run -s -- dangerous-cmd            # Start suspended (ENTER to run)
zellij run -n "build" -- make             # Named pane

Edit Files

zellij edit src/main.rs                   # Open in $EDITOR pane
zellij edit -f src/main.rs                # Floating editor pane
zellij edit -l 42 src/main.rs             # Open at line 42

Actions (from outside or within)

zellij action new-pane                    # New pane
zellij action new-pane --floating         # New floating pane
zellij action new-tab --name "build"      # Named new tab
zellij action go-to-tab 2                 # Switch to tab 2
zellij action dump-layout                 # Export current layout to stdout
zellij action dump-screen /tmp/out.txt    # Dump pane content
zellij action switch-mode locked          # Enter locked mode
zellij action toggle-floating-panes       # Toggle floats
zellij action rename-session "work"       # Rename session

Setup Utilities

zellij setup --dump-config                # Print default config
zellij setup --dump-layout default        # Print default layout
zellij setup --dump-layout compact        # Print compact layout
zellij setup --dump-swap-layout default   # Print swap layout
zellij setup --generate-completion fish   # Fish completions
zellij setup --generate-auto-start fish   # Auto-start script
zellij setup --check                      # Validate config

Convenience Aliases (from shell completions)

---

Session Resurrection

Your config has resurrection enabled (session_serialization true, serialize_pane_viewport true).

What's saved: Layout, pane structure, commands, visible viewport, scrollback. What's NOT saved: Running processes. Commands show "Press ENTER to run..." on resurrection.

zellij ls                                 # Shows EXITED sessions
zellij attach <exited-session>            # Resurrect it
zellij attach <name> --force-run-commands # Skip ENTER confirmation
zellij delete-session <name>              # Permanently remove

Serialized sessions are human-readable KDL layout files in the cache directory. They can be shared, modified, or loaded directly with zellij --layout.

---

Floating & Stacked Panes

Floating: Ctrl p then w (toggle), e (embed/float), or Alt f (if default binds) Pinned floating: Always-on-top panes (pin via CLI: zellij run -f --pinned -- cmd) Stacked: Panes in a stack where only the focused one is expanded. Define in layouts with stacked=true.

---

Plugins (Built-in)

Load in layouts:

pane size=1 borderless=true {
    plugin location="zellij:compact-bar"
}

---

Troubleshooting

Fish Shell Integration

# Nesting prevention (add to config.fish or conf.d/)
if status is-interactive; and not set -q ZELLIJ
    zellij attach -c default
end

# Generate completions
zellij setup --generate-completion fish > ~/.config/fish/completions/zellij.fish

Environment Variables

---

Layout Authoring Quick Reference

layout {
    // Tab template applied to all tabs
    default_tab_template {
        pane size=1 borderless=true { plugin location="zellij:tab-bar" }
        children    // ← where tab content goes
        pane size=2 borderless=true { plugin location="zellij:status-bar" }
    }

    tab name="code" focus=true {
        pane split_direction="vertical" {
            pane size="60%" name="editor" edit="src/main.rs"
            pane size="40%" split_direction="horizontal" {
                pane name="term"
                pane name="test" command="make" { args "test"; }
            }
        }
    }

    tab name="git" {
        pane command="lazygit"
    }

    // Floating panes section
    floating_panes {
        pane x="10%" y="10%" width="80%" height="80%" name="scratch"
    }
}

Key layout attributes

CWD composes: pane cwd → tab cwd → layout cwd → execution directory. Relative paths chain; absolute paths override.

For the full actions reference, theme system, swap layouts, and plugin configuration, see reference.md.