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

bash

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

kdl

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

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

bash

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

bash

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

bash

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)

bash

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

bash

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.

bash

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

(toggle),

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

kdl

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

fish

# 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

kdl

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.

zellij-guide

NPX Install

Tags

SKILL.md Content

Zellij Guide — Personal Reference

Quick Start

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

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)

Modes NOT configured (from defaults)

Your Config Summary

Your Layouts

dev.kdl (3-tab development layout)

Modes Reference (13 total)

CLI Quick Reference

Session Management

Run Commands in Panes

Edit Files

Actions (from outside or within)

Setup Utilities

Convenience Aliases (from shell completions)

Session Resurrection

Floating & Stacked Panes

Plugins (Built-in)

Troubleshooting

Fish Shell Integration

Environment Variables

Layout Authoring Quick Reference

Key layout attributes

zellij-guide

NPX Install

Tags

SKILL.md Content

Zellij Guide — Personal Reference

Quick Start

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

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)

Modes NOT configured (from defaults)

Your Config Summary

Your Layouts

dev.kdl (3-tab development layout)

Modes Reference (13 total)

CLI Quick Reference

Session Management

Run Commands in Panes

Edit Files

Actions (from outside or within)

Setup Utilities

Convenience Aliases (from shell completions)

Session Resurrection

Floating & Stacked Panes

Plugins (Built-in)

Troubleshooting

Fish Shell Integration

Environment Variables

Layout Authoring Quick Reference

Key layout attributes

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)