Zellij sessions, layouts and editor navigation
On this page
Zellij organises a terminal into sessions, tabs and panes. A session runs on the machine where Zellij was started; the terminal window is a client. Disconnecting that client and terminating the session are different actions.
Commands were checked against Zellij 0.44.3. Bindings can be overridden, so consult the current status bar and configuration.
Create and reattach a named session
From a project directory in a terminal outside Zellij:
doc-work is an example name. Check pwd, then detach through the session menu. Default bindings commonly use Ctrl+o to enter session mode; customised bindings may differ.
From the outer terminal, list sessions:
Reattach explicitly:
A session started on an SSH host must be reattached on that host after reconnecting. A local session cannot recover remote processes.
What a layout preserves
Save as ~/.config/zellij/layouts/dev.kdl:
layout {
pane split_direction="vertical" {
pane size="65%"
pane split_direction="horizontal" {
pane
pane
}
}
}
This creates a wide left pane and two stacked right panes without automatically executing project commands. From a regular terminal at the project root:
Layouts can specify programs and directories, but describe workspace construction rather than preserving process memory, connections or unsaved editor data. Layouts
Detach, exit and resurrection
| Action | Process behaviour | Recovery |
|---|---|---|
| Detach client | Session continues | Attach to the same session |
| Exit a pane's program | That task ends | Start the task again |
| Terminate session | Session processes end | Rebuild the workspace |
| Reboot or crash | Original processes no longer run | Reconstruct saved layout/command information |
Resurrection does not restore terminated process memory. Saved commands should not cause deployments or data modifications to be rerun without review. Session resurrection
Reduce key conflicts
This standalone minimal ~/.config/zellij/config.kdl clears defaults and keeps a locked mode plus a small control mode. Back up existing configuration first.
default_mode "locked"
keybinds clear-defaults=true {
locked {
bind "Ctrl g" { SwitchToMode "normal"; }
}
normal {
bind "Ctrl g" { SwitchToMode "locked"; }
bind "n" { NewPane; SwitchToMode "locked"; }
bind "d" { Detach; }
bind "h" { MoveFocus "left"; }
bind "j" { MoveFocus "down"; }
bind "k" { MoveFocus "up"; }
bind "l" { MoveFocus "right"; }
}
}
Locked mode forwards most keys. Ctrl+g enters normal mode; n creates a pane and d detaches. These are the example's bindings, not a description of defaults.
The check also reports configuration and layout directories. Verify paths before syntax, and test both existing and newly created sessions.
Share direction keys with Neovim
Moving with Ctrl+hjkl inside Neovim and then across its boundary requires both sides: smart-splits in Neovim and vim-zellij-navigator in Zellij. Configuring only one side usually completes only half the route.
The remote and input chapter provides both configurations and boundary tests. An older local workaround overrides an internal smart-splits probe; it is version-specific and should not become a default for new installations.
Inspect scrollback as text
EditScrollback opens pane history in an editor. Verify the scrollback editor path before binding the action. The result is useful for search and copying, but is neither a live log nor a guarantee that older output beyond the buffer limit remains available.
Retry failures in a terminal without Zellij. If they disappear, inspect keys, clipboard forwarding and terminal capabilities. Otherwise investigate the terminal or application itself. Theme generation is covered in Matugen.