Zellij Tab and Pane Management

Zellij is a terminal workspace with built-in tab and pane management. Understanding when to use tabs vs panes improves workflow efficiency.

Tabs vs Panes: When to Use Each

Panes (Split Views)

Use panes when:

• Working on one project with multiple views
• Need to see multiple outputs simultaneously
• Related tasks (e.g., code + tests + logs)

Example workflow:

┌────────────┬────────────┐
│            │ git status │
│  neovim    ├────────────┤
│            │   tests    │
└────────────┴────────────┘

Create panes:

• Ctrl-p then n → Split down
• Ctrl-p then d → Split right

Tabs (Separate Workspaces)

Use tabs when:

• Different projects/contexts
• Task-switching between unrelated work
• Keeping workspace states separate

Example setup:

Tab 1: midimaze/     (vault work)
Tab 2: nnt/          (compiler dev)
Tab 3: PhD/          (dissertation)
Tab 4: system admin  (maintenance)

Create tab:

• Ctrl-p then t → New tab

Tab Navigation Shortcuts

Built-in Navigation

Ctrl-p prefix mode:

bash
Ctrl-p t        # Open tab switcher (fuzzy find)
Ctrl-p 1-9      # Jump to tab number
Ctrl-p [        # Previous tab
Ctrl-p ]        # Next tab

Tab switcher (fuzzy find):

1. Press Ctrl-p then t
2. Type partial tab name
3. Arrow keys to select
4. Enter to switch

Custom Keybindings (Alt-based)

Add to ~/.config/zellij/config.kdl:

kdl
keybinds {
    normal {
        bind "Alt h" { GoToPreviousTab; }
        bind "Alt l" { GoToNextTab; }
        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; }
    }
}

Usage:

• Alt-h → Previous tab
• Alt-l → Next tab
• Alt-1 through Alt-5 → Jump to specific tab

Benefit: No Ctrl-p prefix needed for common navigation.

Pane Navigation

Built-in:

bash
Ctrl-p h/j/k/l    # Navigate panes (Vim-style)
Ctrl-p arrows     # Navigate panes (arrow keys)
Ctrl-p f          # Fullscreen current pane (toggle)

Custom (Alt-based):

kdl
keybinds {
    normal {
        bind "Alt Left"  { MoveFocus "Left"; }
        bind "Alt Down"  { MoveFocus "Down"; }
        bind "Alt Up"    { MoveFocus "Up"; }
        bind "Alt Right" { MoveFocus "Right"; }
    }
}

Pane Fullscreen (Adobe Premiere "Tilde" Equivalent)

Zellij's pane fullscreen mode:

bash
Ctrl-p f          # Toggle fullscreen for current pane

Behavior:

• Hides all other panes
• Shows only focused pane
• Press again to restore layout

Use cases:

• Reading long output without distraction
• Editing file in full terminal width
• Watching tests run with full visibility

Alternative: Close other panes with Ctrl-p x (destructive).

Session Management

Why sessions matter:

• Sessions persist layouts + tabs + panes
• Resurrect entire workspace after reboot
• Multiple session per project

Create named session:

bash
zellij -s midimaze-vault

List sessions:

bash
zellij list-sessions

Attach to session:

bash
zellij attach midimaze-vault
# or
zellij attach    # Fuzzy find from list

Kill session:

bash
zellij kill-session midimaze-vault

Ghostty Tabs vs Zellij Tabs

Question: Why use Ghostty tabs when Zellij has tabs?

Answer: Use Zellij tabs for 99% of workflows.

Ghostty Tabs (Rare Use Cases)

When to use Ghostty tabs:

1. Multiple Zellij sessions simultaneously

   Ghostty Tab 1: zellij -s work
   Ghostty Tab 2: zellij -s personal
   Ghostty Tab 3: zellij -s experiments
   

   Each Ghostty tab runs separate Zellij instance.

2. SSH sessions

   Ghostty Tab 1: ssh user@server1 (Zellij on remote)
   Ghostty Tab 2: ssh user@server2 (Zellij on remote)
   Ghostty Tab 3: local Zellij session
   

3. Long-running processes outside Zellij

   Ghostty Tab 1: docker logs -f container (no Zellij)
   Ghostty Tab 2: Zellij normal work
   

For everything else: Use Zellij tabs.

Why? Zellij sessions are resurrectable - entire workspace (tabs + panes + state) survives reboot.

Workflow Recommendation

Optimal setup:

┌─ Ghostty Window ──────────────────────┐
│                                       │
│  ┌─ Zellij Session ─────────────┐   │
│  │                               │   │
│  │  Tab 1: midimaze/             │   │
│  │  ├─ Pane 1: neovim            │   │
│  │  ├─ Pane 2: git status        │   │
│  │  └─ Pane 3: test runner       │   │
│  │                               │   │
│  │  Tab 2: nnt/                  │   │
│  │  ├─ Pane 1: neovim            │   │
│  │  └─ Pane 2: compiler tests    │   │
│  │                               │   │
│  │  Tab 3: PhD/                  │   │
│  │  └─ Pane 1: LaTeX editor      │   │
│  │                               │   │
│  └───────────────────────────────┘   │
│                                       │
└───────────────────────────────────────┘

One Ghostty window, one Zellij session, multiple tabs/panes.

Configuration Tips

Rename tabs for clarity:

bash
Ctrl-p r    # Rename current tab

Example names:

• vault instead of midimaze/
• nnt-dev instead of nnt/
• latex instead of PhD/

Easier to navigate with Ctrl-p t (fuzzy finder).

Persistent layouts:

Create ~/.config/zellij/layouts/coding.kdl:

kdl
layout {
    tab name="editor" {
        pane size=1 borderless=true {
            plugin location="zellij:tab-bar"
        }
        pane split_direction="vertical" {
            pane
            pane split_direction="horizontal" {
                pane
                pane
            }
        }
    }
}

Load layout:

bash
zellij --layout ~/.config/zellij/layouts/coding.kdl

Common Pitfalls

❌ Using Ghostty tabs for project switching

• Lose session state on restart
• No resurrect capability
• Extra cognitive overhead

✅ Use Zellij tabs instead

• Sessions persist
• zellij attach restores entire workspace
• Faster navigation (Ctrl-p t)

❌ Creating too many panes

• Hard to see individual panes
• Cluttered workspace
• Better to use tabs

✅ Limit to 2-4 panes per tab

• Primary + support panes
• Use fullscreen (Ctrl-p f) when needed
• Switch tabs for different contexts

Keyboard Shortcut Reference

Links

Zellij Documentation

• URL: https://zellij.dev/documentation/↗
• Summary: Official guide for Zellij terminal workspace
• Related: Ghostty, tmux, Terminal Multiplexers