Zellij Configuration Reference

Modern terminal multiplexer with tmux-compatible keybinds and zjstatus integration.

Mode System

Zellij uses a modal interface. Press a mode key to enter that mode, then use mode-specific bindings.

Keybind	Mode	Exit
Ctrl g	Locked (passthrough)	Ctrl g
Ctrl p	Pane	Ctrl p / Esc
Ctrl t	Tab	Ctrl t / Esc
Ctrl n	Resize	Ctrl n / Esc
Ctrl h	Move	Ctrl h / Esc
Ctrl s	Scroll	Ctrl s / Esc
Ctrl o	Session	Ctrl o / Esc
Ctrl b / Ctrl Space	Tmux	Esc

Tmux Mode (Prefix Style)

Familiar tmux-like bindings. Press Ctrl Space or Ctrl b, then:

Pane Management:

Key	Action
| or %	Split right
- or "	Split down
h/j/k/l or arrows	Navigate panes
x	Close pane
z	Toggle fullscreen
o	Focus next pane
space	Next layout

Tab Management:

Key	Action
c	New tab
n	Next tab
p	Previous tab
1-9	Go to tab N
,	Rename tab

Session:

Key	Action
d	Detach
Ctrl b	Send literal Ctrl-b
Ctrl Space	Send literal Ctrl-Space

Pane Mode (Ctrl p)

Key	Action
h/j/k/l or arrows	Move focus
n	New pane (auto direction)
d	New pane down
r	New pane right
s	New stacked pane
x	Close pane
f	Toggle fullscreen
e	Toggle embed/floating
w	Toggle floating panes
z	Toggle pane frames
i	Pin pane
c	Rename pane
p	Switch focus

Tab Mode (Ctrl t)

Key	Action
h/l or arrows	Previous/next tab
n	New tab
x	Close tab
r	Rename tab
1-9	Go to tab N
b	Break pane to new tab
[	Break pane left
]	Break pane right
s	Sync tab (send input to all panes)
tab	Toggle between last two tabs

Resize Mode (Ctrl n)

Key	Action
h/j/k/l or arrows	Increase size in direction
H/J/K/L	Decrease size in direction
+ / =	Increase overall
-	Decrease overall

Move Mode (Ctrl h)

Key	Action
h/j/k/l or arrows	Move pane in direction
n / tab	Move pane forward
p	Move pane backward

Scroll Mode (Ctrl s)

Key	Action
j/k or arrows	Scroll line by line
d / u	Half page down/up
Ctrl f / Ctrl b	Full page down/up
PageDown / PageUp	Full page down/up
s	Enter search mode
e	Edit scrollback in $EDITOR
Ctrl c	Exit to normal mode

Search Mode (from Scroll)

Key	Action
n	Next match
p	Previous match
c	Toggle case sensitivity
w	Toggle wrap
o	Toggle whole word

Session Mode (Ctrl o)

Key	Action
w	Session manager (switch/create)
d	Detach
c	Configuration
p	Plugin manager
a	About
s	Share session

Global Bindings (Always Available)

Keybind	Action
Alt h/j/k/l	Move focus (or tab if at edge)
Alt arrows	Move focus (or tab if at edge)
Ctrl Shift arrows	Move focus (pane only)
Alt Shift arrows	Move focus (pane only)
Alt \	Split right (vertical)
Alt |	Split down (horizontal)
Alt Shift w	Close pane
Ctrl Alt Shift arrows	Resize in direction
Alt + / Alt -	Resize increase/decrease
Alt [ / Alt ]	Previous/next layout
Alt f	Toggle floating panes
Alt n	New pane
Alt i / Alt o	Move tab left/right
Alt p	Toggle pane in group
Alt Shift p	Toggle group marking
Ctrl q	Quit Zellij

Locked Mode (Ctrl g)

All Zellij keybinds disabled, keys pass through to terminal. Press Ctrl g again to exit.

CLI Commands

# Start new session
zellij

# Named session
zellij -s mysession

# Attach to existing
zellij attach mysession

# List sessions
zellij list-sessions
zellij ls

# Kill session
zellij kill-session mysession
zellij kill-all-sessions

# Run command in new pane
zellij run -- htop

# Run in floating pane
zellij run -f -- htop

# Edit file in new pane
zellij edit ~/.zshrc

# Open specific layout
zellij --layout compact

Configuration Files

~/.config/zellij/
├── config.kdl           # Main configuration
├── layouts/
│   └── tenseley.kdl     # Custom layout with zjstatus
├── themes/
│   └── tenseley.kdl     # Tmux-inspired color theme
└── plugins/
    └── zjstatus.wasm    # Custom status bar plugin

Layout Structure

Current layout (tenseley):

• Top: Default Zellij tab bar
• Middle: Content panes
• Bottom: zjstatus (session, hostname, mode, datetime)

Theme Colors

Element	Color	Hex
Active border/accent	Green	#7bd88f
Inactive border	Muted gray	#4a5162
Main text	Light gray	#b8c0cc
Muted text	Gray	#8b94a6
Alert/error	Red	#e05f5f
Background	Dark	#1f2430

Tips & Workflows

Quick pane creation:

• Alt n creates a new pane instantly (no mode switch needed)
• Alt f toggles floating panes for temporary work

Tmux muscle memory:

• Ctrl Space or Ctrl b enters tmux mode
• Most tmux bindings work: %, ", c, n, p, x, z, d

Session management:

• Ctrl o then w opens session manager
• Sessions auto-serialize for resurrection

Passthrough mode:

• Ctrl g locks Zellij, passing all keys to the terminal
• Useful for nested multiplexers or apps with conflicting binds

Layouts:

• Alt [ / Alt ] cycles through layout presets
• space in tmux mode also cycles layouts

Differences from Tmux

Feature	Tmux	Zellij
Prefix	Single key then command	Modal (stay in mode) or tmux-style
Plugins	TPM + shell scripts	WebAssembly (WASM)
Config format	Shell-like	KDL
Session restore	tmux-resurrect plugin	Built-in
Floating panes	tmux-popup	Native
Stacked panes	N/A	Native