Learn Zellij - Keybindings & Mode System

#Introduction

Everything you press in Zellij — Ctrl+p, Ctrl+t, Ctrl+o, even Alt+n — is part of a single system that unifies this entire tool: the mode system. In episode 3 you already used it without realizing it. This episode 4 will dissect that concept fully, because understanding modes is the most fundamental difference between Zellij and tmux, and the key to making Zellij feel natural rather than memorized.

Let's be honest about what happens when a beginner uses tmux: they remember "Ctrl+b then c for a new window", "Ctrl+b then % for a split", and "Ctrl+b then d to detach". When they forget, there's no hint — they have to open man tmux or rely on a cheat sheet. Zellij redesigned this model from scratch. Instead of one prefix burdened with every action, Zellij groups actions into modes, and each mode displays its own hints on screen.

In this episode we'll discuss the difference between mode-based keybinding and prefix keys, the full map of all modes (Ctrl+p, Ctrl+t, Ctrl+n, Ctrl+h, Ctrl+s, Ctrl+o, Ctrl+g, Ctrl+q), the role of Esc and Enter as the way back to Normal mode, the Alt+ quick keys that work directly, and Tmux mode (Ctrl+b) for those of you coming from tmux. Let's begin.

#Mode-Based vs Prefix Key

To understand why Zellij chose modes, we have to be honest about the problems the tmux prefix key model brings. In tmux, every action is a prefix + key sequence: Ctrl+b followed by % to split, Ctrl+b followed by n for the next window, and so on. This model is simple to learn, but it breaks at scale.

The first problem is no hints. When you press Ctrl+b in tmux, nothing appears on screen. You have to remember the exact combination, or open the documentation. Zellij eliminates this problem: pressing Ctrl+p immediately turns the status bar into an interactive hint showing every pane action along with its key. Forget how to resize? Press Ctrl+n and read the screen — no memorization needed.

The second problem is one prefix for all domains. Ctrl+b manages windows, panes, detach, sessions, and hundreds of other actions — all competing for a single namespace. The result is unintuitive combinations (why does a vertical split use %?) and conflicts with application keybindings. Zellij splits this namespace into per-domain modes: pane matters in Pane mode, tab matters in Tab mode, session matters in Session mode. Each domain has its own roomy key space.

The third problem is indistinguishable context. In tmux, the same prefix is used for different actions depending on whether you're in a session or not. Zellij handles this with Locked mode and explicit modes: when you're in Scroll mode, keys mean scroll actions; in Pane mode, keys mean pane actions. You always know which mode you're in — the status bar displays it continuously.

This is the core of Zellij's philosophy: interaction shouldn't be memorized; it should be readable. You'll still memorize frequently used keybindings over time, but that happens naturally, not as a prerequisite.

#The Complete Mode Map

Zellij has eight main trigger modes accessed via Ctrl+ combinations, plus a special mode explained in its own section. Here's the complete map:

Note the consistent pattern: every major work domain has a trigger that's easy to press and adjacent on the keyboard. Ctrl+p (Pane), Ctrl+t (Tab), Ctrl+s (Scroll), Ctrl+o (Session) — all cluster in the lower-left area of the keyboard, easy to reach without moving your hands.

Pane mode (Ctrl+p) is the most used mode. Here you create panes (n), split (d/r), close (x), move focus (h/j/k/l), zoom (f), and manage floating panes (w). Tab mode (Ctrl+t) handles tab creation (n), navigation (h/l), rename (r), and closing (x). Session mode (Ctrl+o) holds the top-level actions: detach (d), rename session (r), and return to the session list (s).

Scroll mode (Ctrl+s) switches the active pane from direct input to browsing history. Press j/k to move line by line, Ctrl+f/Ctrl+b for a page, and g/G to jump to the start/end. From Scroll mode you can enter Search mode with Ctrl+f and start typing a search pattern — a capability we'll fully dissect in episode 6. Locked mode (Ctrl+g) is an emergency switch that blocks all input so no keystroke accidentally leaks into the shell — often used during presentations or when you step away from the laptop for a moment.

#Esc & Enter: Returning to Normal Mode

Every mode has a consistent way out: Esc or Enter always returns you to Normal mode. This consistency is what makes modes feel safe — no matter how far you explore, there's a universal key to get back to base.

Normal mode is Zellij's center of gravity. From here you enter any mode (Ctrl+p, Ctrl+t, Ctrl+o, and so on), and every mode returns here. In Normal mode, the Alt+... quick keys are active, and no keybinding interferes with normal typing — you can type shell commands freely because Normal mode doesn't capture keystrokes.

A habit to plant early: if you feel "stuck" inside a mode, press Esc a few times. Most stuck feelings in Zellij are actually you still being inside an unnoticed mode, and Esc always solves this. The status bar shows the active mode in the corner — get used to reading that corner before pressing keys.

Beyond Esc/Enter, Zellij provides a very useful discovery shortcut: press ? inside any mode to display that mode's complete keybinding list. Instead of opening documentation every time you're confused, press ? and read the hint that appears instantly. This is a concrete example of the "readable, not memorized" philosophy.

#Normal Mode Quick Keys

The Ctrl+... modes are thorough, but for the most frequent actions, entering a mode every time feels slow. Zellij answers this with quick keys: Alt+... combinations that work directly in Normal mode, without entering a mode first.

The four quick keys that most define daily speed are Alt+h/j/k/l for moving focus between panes. Once you're used to them, your hands never leave the home row: Alt+l to move to the right pane, Alt+n to open a new pane, Alt+- to give more room, and so on. These quick keys are what make Zellij feel like it "flows" compared to switching modes for every small action.

Alt+f toggles floating panes: making them appear above content or hiding them again. Alt+[ and Alt+] shift the layout between defined variants — you'll feel their benefit more deeply in episode 7 when we cover layout swapping. The key point for now: quick keys are an acceleration layer on top of modes, not a replacement. Modes remain as a complete, always-readable fallback.

#Tmux Mode for Migrants

Zellij recognizes that many users come from tmux with years of trained muscle memory. Forcing them to re-memorize everything from scratch is wasteful. The solution is Tmux mode: a special mode activated with Ctrl+b that emulates common tmux keybindings.

When you press Ctrl+b then %, Zellij splits to the right — exactly like tmux. Ctrl+b then " to split down, Ctrl+b then x to close a pane, Ctrl+b then c to create a new tab, and Ctrl+b then arrows to move focus. For those of you newly migrated, Tmux mode becomes a bridge: keep working with old habits while slowly shifting to Zellij's richer modes.

Tmux mode also confirms one important thing: Zellij's mode system is data, not destiny. Mode definitions, the keybindings inside them, even the presence of Tmux mode itself, all live in the KDL configuration file and can be fully changed. In episodes 8 and 9 you'll open that file and see how the entire mode map we discussed in this episode is just one set of default configuration that you fully control.

As a final comparison, here's how the same actions are done via the CLI — proving that what you see on screen can also be controlled from outside, the foundation for automation in episode 13:

tmux split-window -v

zellij action new-pane

zellij action new-pane sends a command to the active session exactly like pressing a keybinding — only this time it can be run from a script. This is the power of modes built on a clear protocol: keyboard interaction and program interaction use the same path.

#Common Pitfalls

1. Pressing a Ctrl+ combination then immediately an action key without a pause. Zellij modes wait for the next action; if you press Ctrl+p then immediately n without releasing Ctrl, the combination can be caught as a different character. Press Ctrl+p, release, then press n.
2. Forgetting that Esc and Enter always return to Normal mode. When a keybinding doesn't seem to respond, check the status bar and press Esc — it's almost always the fix.
3. Assuming Tmux mode is full tmux emulation. Keybindings outside the curated subset aren't available. Don't let Tmux mode become an obstacle to learning Zellij's real mode system.
4. Mixing up Resize and Move. Ctrl+n changes size; Ctrl+h moves position. Getting these backwards is a confusing experience, so make sure of the right mode before pressing arrows.
5. Memorizing all keybindings at once. This is a shortcut to frustration. Memorize three first (Ctrl+p, Ctrl+t, Alt+h/j/k/l), let ? help you in between, and the rest will stick on their own with use.

#Closing

This episode 4 is the key that unlocks Zellij's full power. You've understood why mode-based keybinding beats tmux's prefix keys — hints always appear, actions are organized per domain, and editor conflicts are handled explicitly. You've mastered the complete mode map: Ctrl+p Pane, Ctrl+t Tab, Ctrl+n Resize, Ctrl+h Move, Ctrl+s Scroll, Ctrl+o Session, Ctrl+g Locked, and Ctrl+q Quit. You know that Esc and Enter are the universal way back to Normal mode, the Alt+... quick keys accelerate everyday actions, and Tmux mode (Ctrl+b) bridges the arrival from tmux.

Key takeaways:

• Modes turn interaction from memorization into reading — the hints are always in the status bar.
• Every major work domain has its own mode; there's no single prefix burdened with everything.
• Esc and Enter always return to Normal mode; ? shows the active mode's keybindings.
• The Alt+h/j/k/l, Alt+n, Alt+f, Alt+=/Alt+-, Alt+[/Alt+] quick keys work directly without entering a mode.
• Tmux mode (Ctrl+b) is a migration bridge providing a subset of tmux keybindings.
• Modes are data that can be fully reconfigured — not locked-in behavior.

Now the mode system is yours. The operational foundation from episode 3 and the modes from episode 4 will be the language used throughout this series. In episode 5 we go deeper into advanced pane management: resizing, focus, zoom, efficient closing, toggling pane frames, and the pinned and stacked pane concepts that bring layered workflows. See you in episode 5!