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)

Key Action

Ctrl h

Move focus / tab left

Ctrl l

Move focus / tab right

Ctrl j

Move focus down

Ctrl k

Move focus up

Ctrl n

New pane (auto direction)

Ctrl s

New pane down

Ctrl v

New pane right

Ctrl -

New pane down

Ctrl /

New pane right

Ctrl x

Close focused pane

Ctrl z

Toggle fullscreen

Ctrl t

New tab

Ctrl w

Close tab

Ctrl 1-5

Go to tab 1-5

Ctrl q

Quit

Ctrl d

Detach

Ctrl p

→ Pane mode

Ctrl r

→ Resize mode

Ctrl m

→ Move mode

Ctrl g

→ Locked mode

Ctrl b

→ Scroll mode

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

Key Action

h/j/k/l

Move focus

n

New pane

x

Close pane

f

Toggle fullscreen

w

Toggle floating panes

e

Toggle embed/float

r

Rename pane

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

Key Action

h/j/k/l

Resize in direction

H/J/K/L

Increase in direction

=

Increase size

Decrease size

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

Key Action

h/j/k/l

Move pane in direction

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

Key Action

j/k

Scroll down/up

Ctrl d / Ctrl u

Half page down/up

g

Scroll to top

G

Scroll to bottom

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)

Mode Purpose Your binding

normal

Default operations (default)

locked

Pass-through (safety) Ctrl g

pane

Pane management Ctrl p

resize

Resize panes Ctrl r

move

Move panes Ctrl m

scroll

Scroll buffer Ctrl b

tab

Tab management (not bound)

search

Search in scrollback (not bound)

entersearch

Type search query (not bound)

renametab

Rename a tab (not bound)

renamepane

Rename a pane (not bound)

session

Session management (not bound)

tmux

tmux compatibility (not bound)

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)

Alias Expands to

zr

zellij run --

zrf

zellij run --floating --

ze

zellij edit

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)

Plugin Location Description

tab-bar

zellij:tab-bar

Tab bar (1 line)

status-bar

zellij:status-bar

Status bar with keybind hints (2 lines)

compact-bar

zellij:compact-bar

Combined tab+status (1 line)

strider

zellij:strider

File browser sidebar

session-manager

zellij:session-manager

Session switcher + resurrection UI

filepicker

zellij:strider

File picker (cwd based)

configuration

zellij:configuration

Runtime config editor

plugin-manager

zellij:plugin-manager

Plugin management UI

Load in layouts:

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

Troubleshooting

Issue Fix

macOS Alt key not working Configure in terminal app (iTerm2: Profiles → Keys → Left Option = Esc+)

Copy not working Add copy_command "pbcopy" to config

Font/character issues Use Nerd Font or simplified_ui true

Ctrl+H triggers Move mode Terminal sends Ctrl+H as backspace — remap in terminal or Zellij

Nesting prevention Check $ZELLIJ env var before starting

Mouse selection Hold SHIFT to bypass Zellij mouse capture

Styled underline colors wrong Add styled_underlines false

Config not loading Check zellij setup --check and verify path

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

Variable Description

ZELLIJ

Set to 0 inside a session (use for nesting prevention)

ZELLIJ_SESSION_NAME

Current session name

ZELLIJ_CONFIG_DIR

Override config directory

ZELLIJ_CONFIG_FILE

Override config file

ZELLIJ_AUTO_ATTACH

Auto-attach to existing session

ZELLIJ_AUTO_EXIT

Exit shell when Zellij exits

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

Attribute Applies to Values

split_direction

pane "vertical" , "horizontal"

size

pane "50%" or fixed int (lines/cols)

command

pane Command to execute

args

child of command pane "arg1" "arg2"

edit

pane File path (opens in $EDITOR)

cwd

pane, tab, layout Working directory

name

pane, tab Display name

focus

pane, tab true for initial focus

borderless

pane true to hide frame

close_on_exit

pane Close when command exits

start_suspended

pane Wait for ENTER

stacked

pane Stack children

plugin location

child block Plugin URL

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.