Zellij
My Zellij setup uses Ctrl-f as the prefix, Vim-style navigation, and one top tab bar. Start with the keybinding map, or choose a feature below.
The built-in Nord preset documents the palette and current native theme examples.
Start a session
Section titled “Start a session”Enable Zellij in your machine settings, then install the selected tools with make install. The guides below describe the managed modern configuration.
zjzj workAfter pulling helper or status plugin updates, run make zellij-status zellij to rebuild the commands and status plugin and refresh their links. Full make install includes this step for the patched and main runtimes.
zj attaches to or creates main; zj work chooses a session named work. Ctrl-f d detaches and keeps programs running. Run the same command to return.
If a first-use permission prompt appears in the top bar, focus it with Ctrl-f k and press y. After updating Zellij or its configuration, start a new session to use the new features; finish or save work before restarting older sessions.
Familiar keys
Section titled “Familiar keys”Press Ctrl-f, release it, then press the next key. Uppercase letters need Shift. Esc, Enter, or Ctrl-c cancels the prefix. Most shortcuts immediately return control to the application.
The keybinding map lists shortcuts, aliases, and keys inside modes. Ctrl-f p pastes copied session text; Ctrl-f Ctrl-p switches tabs.
Navigation
Section titled “Navigation”| Feature | Use it to… |
|---|---|
| Smart pane navigation | Move through editor splits and terminal panes with the same keys |
| Status bar and tab titles | Read tab positions, activity, and keyboard modes |
| Tab picker | Find a tab and preview its panes |
| Session picker | Switch between running workspaces |
| Swap tabs | Exchange two tab positions |
Pane arrangement
Section titled “Pane arrangement”| Feature | Use it to… |
|---|---|
| Move a pane | Move one running pane into a new or existing tab |
| Gather panes | Bring a tab’s live panes into another tab |
| Equalize panes | Balance a row or column, or choose a layout |
| Golden-ratio sizing | Size a full-height left pane for comfortable work |
Shared popup and session shutdown
Section titled “Shared popup and session shutdown”| Feature | Use it to… |
|---|---|
| Shared popup | Keep a scratch shell across tabs and sessions |
| Command palette | Complete and run actions, or find a live pane, tab, or session |
| Create and rename sessions | Open or name a workspace |
| Detach one client | Disconnect a selected view while leaving programs running |
| Shut down a session | Deliberately end one session with confirmation |
Forwarded SSH agents
Section titled “Forwarded SSH agents”Use SSH and forwarded agents to open remote workspaces and reconnect without losing authentication in existing panes. The same page covers the shared popup and 1Password agents.
Text and attention
Section titled “Text and attention”| Feature | Use it to… |
|---|---|
| Copy and paste | Select scrollback text and choose the right paste source |
| Attention and triage | Visit requests, watch output, and mute panes |
| Notifications and history | Review events with a preview of their source panes |
History and recovery
Section titled “History and recovery”Detaching preserves running programs. After a session exits, the session manager may offer to reconstruct its layout and rerun commands; that does not restore program memory. The fuzzy session picker lists running sessions only.
Scrollback keeps up to 100,000 live lines per pane and up to 10,000 lines for recovery. A crash can lose recent output. The shared popup does not restore its running work after a server exit or reboot.
The patched runtime supports hide_scroll_indicator_when_idle, which defaults to false to preserve upstream behavior. This configuration sets it to true, hiding the SCROLL counter on active and inactive panes at live output. Scrolling back shows the position; returning to the bottom hides it again. Floating-pane pin controls are unchanged. After updating, run make zellij-runtime and restart existing session servers to load the new runtime. The option can then be changed by reloading configuration. Release and main runtime choices keep their upstream display.
Differences that remain
Section titled “Differences that remain”Older installations may use the legacy configuration: tab numbering starts at 1, several custom shortcuts are unavailable, and copying differs. See legacy differences when your keys do not match.
Moving a live pane to another session, exact cell sizing, and tmux’s timed repeat window are not supported. The relevant feature pages explain the alternatives.