Zellij keybindings: the Alt layer that doesn't fight your shell

What clearing the default Zellij keybindings buys

One attribute does the demolition work. keybinds clear-defaults=true tells Zellij to throw away its entire stock keymap — every mode, every chord — and start from whatever you write next. To see the scale of what's being thrown away, ask Zellij to print its built-in config:

$ zellij setup --dump-config | wc -l
     520
$ zellij setup --dump-config | head -14
// If you'd like to override the default keybindings completely, be sure to change "keybinds" to "keybinds clear-defaults=true"
keybinds {
    normal {
        // uncomment this and adjust key if using copy_on_select=false
        // bind "Alt c" { Copy; }
    }
    locked {
        bind "Ctrl g" { SwitchToMode "Normal"; }
    }
    resize {
        bind "Ctrl n" { SwitchToMode "Normal"; }
        bind "h" "Left" { Resize "Increase Left"; }
        bind "j" "Down" { Resize "Increase Down"; }
        bind "k" "Up" { Resize "Increase Up"; }

Five hundred twenty lines, organized into modes — locked, resize, pane, tab, and friends — each a little room you enter, act in, and leave. The replacement is 35 lines, every binding lives in normal mode, and you copy it whole:

keybinds clear-defaults=true {
    normal {
        bind "Alt h" { MoveFocus "Left"; }
        bind "Alt l" { MoveFocus "Right"; }
        bind "Alt j" { MoveFocus "Down"; }
        bind "Alt k" { MoveFocus "Up"; }
        bind "Alt H" { Resize "Increase Left"; }
        bind "Alt L" { Resize "Increase Right"; }
        bind "Alt J" { Resize "Increase Down"; }
        bind "Alt K" { Resize "Increase Up"; }
        bind "Alt 1" { GoToTab 1; }
        bind "Alt 2" { GoToTab 2; }
        bind "Alt 3" { GoToTab 3; }
        bind "Alt 4" { GoToTab 4; }
        bind "Alt 5" { GoToTab 5; }
        bind "Alt n" { NewTab; }
        bind "Alt [" { GoToPreviousTab; }
        bind "Alt ]" { GoToNextTab; }
        bind "Alt d" { NewPane "Right"; }
        bind "Alt D" { NewPane "Down"; }
        bind "Alt w" { CloseFocus; }
        bind "Alt f" { ToggleFocusFullscreen; }
        bind "Alt z" { ToggleFloatingPanes; }
        bind "Alt q" { Detach; }
    }
    shared_except "normal" {
        bind "Esc" { SwitchToMode "Normal"; }
    }
}

theme "catppuccin-mocha"
default_layout "compact"
pane_frames false
simplified_ui true
on_force_close "quit"

Read it as four families. The compass: Alt+h/j/k/l moves focus left, down, up, right — vim's home-row directions, sixty years of muscle memory borrowed without buying vim itself. Hold Shift and the same compass resizes instead. Splits: Alt+d divides right, Alt+D divides down — d for divide, Shift for the other axis. Tabs: Alt+n for new, Alt+1 through Alt+5 to jump, Alt+[ and Alt+] to cycle. Verbs: Alt+w closes the focused pane, Alt+f fullscreens it, Alt+z toggles floating panes, and Alt+q detaches — the chord that detach and reattach turns into the keystone habit of this whole setup.

The shared_except "normal" block is the escape hatch: if a plugin or a stray key ever lands you in some mode, Esc walks you home. The five closing lines are taste plus one trap: catppuccin-mocha matches the studio's Ghostty theme, default_layout "compact" collapses the two UI bars into one slim line, pane_frames false and simplified_ui true strip borders and arrow glyphs. And on_force_close "quit" changes what closing a window means — slam a window without detaching and the session ends with it, so Alt+q has to come first.

Install it in four steps

1. 01Create the config file: run mkdir -p ~/.config/zellij, then paste the block above into ~/.config/zellij/config.kdl with your editor of choice.
2. 02Ask Zellij to grade it: zellij setup --check validates the file and tells you where it looked. You want the fourth line: Well defined.
3. 03Restart the session. Config loads when a session starts, so finish the old one cleanly: type exit in each pane, then start fresh with zellij -s studio.
4. 04Run the 60-second drill below, once a day for a week, until the chords stop being facts and become reflexes.

$ zellij setup --check | head -4
[Version]: "0.43.1"
[CONFIG DIR]: "~/.config/zellij"
[LOOKING FOR CONFIG FILE FROM]: "~/.config/zellij/config.kdl"
[CONFIG FILE]: Well defined.

The restart in step 3 matters more than it looks: the new keymap and the compact layout only apply to sessions started after the change, so an old session keeps behaving — and colliding — the old way until you end it.

THE 60-SECOND DRILL — daily, for one week
Alt+d          split right
Alt+D          split down
Alt+h/j/k/l    walk all three panes, twice around
Alt+f          fullscreen the focused pane … Alt+f to undo
Alt+n          new tab
Alt+1, Alt+2   bounce between tabs
Alt+[          back one tab
Alt+w  Alt+w   close both extra panes
Alt+q          detach
zellij attach studio        and you're home

Why a flat keymap wins

Modes exist so twenty keys can do a hundred things. But you don't use a hundred things — you use about a dozen, hundreds of times a day, often while Claude is mid-stream and your attention is rented out. A mode is a tiny context switch; a dozen of them an hour is a tax on exactly the resource this setup exists to protect.

The Alt namespace is the other half of the argument. The Ctrl row is already spoken for — Ctrl+p is shell history, Ctrl+r is search, and Claude Code listens for its own keys — while Option on a Mac mostly types accented characters nobody asked for. One line in the Ghostty config, macos-option-as-alt = true, is what frees it: Ghostty hands Option to Zellij as a clean Alt, and an entire modifier row becomes yours.

Notice also what the config doesn't rebind. There's no scroll mode, because Zellij's mouse support stays on by default — two fingers on the trackpad scroll the focused pane's history without entering anything. Keeping a key chord for a thing your hand already does free is exactly the clutter this file exists to refuse.

The full bind syntax — multiple keys per action, chained actions per key, and exactly what clear-defaults does globally versus per mode — is in the Zellij keybindings documentation. The chords themselves go to work in the 2×2 terminal layout, where four of them build a working grid in under ten seconds.