@@ -0,0 +1,254 @@ |
| 1 | +# Zellij Configuration Reference |
| 2 | + |
| 3 | +Modern terminal multiplexer with tmux-compatible keybinds and zjstatus integration. |
| 4 | + |
| 5 | +## Mode System |
| 6 | + |
| 7 | +Zellij uses a modal interface. Press a mode key to enter that mode, then use mode-specific bindings. |
| 8 | + |
| 9 | +| Keybind | Mode | Exit | |
| 10 | +|---------|------|------| |
| 11 | +| `Ctrl g` | Locked (passthrough) | `Ctrl g` | |
| 12 | +| `Ctrl p` | Pane | `Ctrl p` / `Esc` | |
| 13 | +| `Ctrl t` | Tab | `Ctrl t` / `Esc` | |
| 14 | +| `Ctrl n` | Resize | `Ctrl n` / `Esc` | |
| 15 | +| `Ctrl h` | Move | `Ctrl h` / `Esc` | |
| 16 | +| `Ctrl s` | Scroll | `Ctrl s` / `Esc` | |
| 17 | +| `Ctrl o` | Session | `Ctrl o` / `Esc` | |
| 18 | +| `Ctrl b` / `Ctrl Space` | Tmux | `Esc` | |
| 19 | + |
| 20 | +## Tmux Mode (Prefix Style) |
| 21 | + |
| 22 | +Familiar tmux-like bindings. Press `Ctrl Space` or `Ctrl b`, then: |
| 23 | + |
| 24 | +**Pane Management:** |
| 25 | +| Key | Action | |
| 26 | +|-----|--------| |
| 27 | +| `\|` or `%` | Split right | |
| 28 | +| `-` or `"` | Split down | |
| 29 | +| `h/j/k/l` or arrows | Navigate panes | |
| 30 | +| `x` | Close pane | |
| 31 | +| `z` | Toggle fullscreen | |
| 32 | +| `o` | Focus next pane | |
| 33 | +| `space` | Next layout | |
| 34 | + |
| 35 | +**Tab Management:** |
| 36 | +| Key | Action | |
| 37 | +|-----|--------| |
| 38 | +| `c` | New tab | |
| 39 | +| `n` | Next tab | |
| 40 | +| `p` | Previous tab | |
| 41 | +| `1-9` | Go to tab N | |
| 42 | +| `,` | Rename tab | |
| 43 | + |
| 44 | +**Session:** |
| 45 | +| Key | Action | |
| 46 | +|-----|--------| |
| 47 | +| `d` | Detach | |
| 48 | +| `Ctrl b` | Send literal Ctrl-b | |
| 49 | +| `Ctrl Space` | Send literal Ctrl-Space | |
| 50 | + |
| 51 | +## Pane Mode (`Ctrl p`) |
| 52 | + |
| 53 | +| Key | Action | |
| 54 | +|-----|--------| |
| 55 | +| `h/j/k/l` or arrows | Move focus | |
| 56 | +| `n` | New pane (auto direction) | |
| 57 | +| `d` | New pane down | |
| 58 | +| `r` | New pane right | |
| 59 | +| `s` | New stacked pane | |
| 60 | +| `x` | Close pane | |
| 61 | +| `f` | Toggle fullscreen | |
| 62 | +| `e` | Toggle embed/floating | |
| 63 | +| `w` | Toggle floating panes | |
| 64 | +| `z` | Toggle pane frames | |
| 65 | +| `i` | Pin pane | |
| 66 | +| `c` | Rename pane | |
| 67 | +| `p` | Switch focus | |
| 68 | + |
| 69 | +## Tab Mode (`Ctrl t`) |
| 70 | + |
| 71 | +| Key | Action | |
| 72 | +|-----|--------| |
| 73 | +| `h/l` or arrows | Previous/next tab | |
| 74 | +| `n` | New tab | |
| 75 | +| `x` | Close tab | |
| 76 | +| `r` | Rename tab | |
| 77 | +| `1-9` | Go to tab N | |
| 78 | +| `b` | Break pane to new tab | |
| 79 | +| `[` | Break pane left | |
| 80 | +| `]` | Break pane right | |
| 81 | +| `s` | Sync tab (send input to all panes) | |
| 82 | +| `tab` | Toggle between last two tabs | |
| 83 | + |
| 84 | +## Resize Mode (`Ctrl n`) |
| 85 | + |
| 86 | +| Key | Action | |
| 87 | +|-----|--------| |
| 88 | +| `h/j/k/l` or arrows | Increase size in direction | |
| 89 | +| `H/J/K/L` | Decrease size in direction | |
| 90 | +| `+` / `=` | Increase overall | |
| 91 | +| `-` | Decrease overall | |
| 92 | + |
| 93 | +## Move Mode (`Ctrl h`) |
| 94 | + |
| 95 | +| Key | Action | |
| 96 | +|-----|--------| |
| 97 | +| `h/j/k/l` or arrows | Move pane in direction | |
| 98 | +| `n` / `tab` | Move pane forward | |
| 99 | +| `p` | Move pane backward | |
| 100 | + |
| 101 | +## Scroll Mode (`Ctrl s`) |
| 102 | + |
| 103 | +| Key | Action | |
| 104 | +|-----|--------| |
| 105 | +| `j/k` or arrows | Scroll line by line | |
| 106 | +| `d` / `u` | Half page down/up | |
| 107 | +| `Ctrl f` / `Ctrl b` | Full page down/up | |
| 108 | +| `PageDown` / `PageUp` | Full page down/up | |
| 109 | +| `s` | Enter search mode | |
| 110 | +| `e` | Edit scrollback in $EDITOR | |
| 111 | +| `Ctrl c` | Exit to normal mode | |
| 112 | + |
| 113 | +## Search Mode (from Scroll) |
| 114 | + |
| 115 | +| Key | Action | |
| 116 | +|-----|--------| |
| 117 | +| `n` | Next match | |
| 118 | +| `p` | Previous match | |
| 119 | +| `c` | Toggle case sensitivity | |
| 120 | +| `w` | Toggle wrap | |
| 121 | +| `o` | Toggle whole word | |
| 122 | + |
| 123 | +## Session Mode (`Ctrl o`) |
| 124 | + |
| 125 | +| Key | Action | |
| 126 | +|-----|--------| |
| 127 | +| `w` | Session manager (switch/create) | |
| 128 | +| `d` | Detach | |
| 129 | +| `c` | Configuration | |
| 130 | +| `p` | Plugin manager | |
| 131 | +| `a` | About | |
| 132 | +| `s` | Share session | |
| 133 | + |
| 134 | +## Global Bindings (Always Available) |
| 135 | + |
| 136 | +| Keybind | Action | |
| 137 | +|---------|--------| |
| 138 | +| `Alt h/j/k/l` | Move focus (or tab if at edge) | |
| 139 | +| `Alt arrows` | Move focus (or tab if at edge) | |
| 140 | +| `Ctrl Shift arrows` | Move focus (pane only) | |
| 141 | +| `Alt Shift arrows` | Move focus (pane only) | |
| 142 | +| `Alt \` | Split right (vertical) | |
| 143 | +| `Alt \|` | Split down (horizontal) | |
| 144 | +| `Alt Shift w` | Close pane | |
| 145 | +| `Ctrl Alt Shift arrows` | Resize in direction | |
| 146 | +| `Alt +` / `Alt -` | Resize increase/decrease | |
| 147 | +| `Alt [` / `Alt ]` | Previous/next layout | |
| 148 | +| `Alt f` | Toggle floating panes | |
| 149 | +| `Alt n` | New pane | |
| 150 | +| `Alt i` / `Alt o` | Move tab left/right | |
| 151 | +| `Alt p` | Toggle pane in group | |
| 152 | +| `Alt Shift p` | Toggle group marking | |
| 153 | +| `Ctrl q` | Quit Zellij | |
| 154 | + |
| 155 | +## Locked Mode (`Ctrl g`) |
| 156 | + |
| 157 | +All Zellij keybinds disabled, keys pass through to terminal. Press `Ctrl g` again to exit. |
| 158 | + |
| 159 | +## CLI Commands |
| 160 | + |
| 161 | +```bash |
| 162 | +# Start new session |
| 163 | +zellij |
| 164 | + |
| 165 | +# Named session |
| 166 | +zellij -s mysession |
| 167 | + |
| 168 | +# Attach to existing |
| 169 | +zellij attach mysession |
| 170 | + |
| 171 | +# List sessions |
| 172 | +zellij list-sessions |
| 173 | +zellij ls |
| 174 | + |
| 175 | +# Kill session |
| 176 | +zellij kill-session mysession |
| 177 | +zellij kill-all-sessions |
| 178 | + |
| 179 | +# Run command in new pane |
| 180 | +zellij run -- htop |
| 181 | + |
| 182 | +# Run in floating pane |
| 183 | +zellij run -f -- htop |
| 184 | + |
| 185 | +# Edit file in new pane |
| 186 | +zellij edit ~/.zshrc |
| 187 | + |
| 188 | +# Open specific layout |
| 189 | +zellij --layout compact |
| 190 | +``` |
| 191 | + |
| 192 | +## Configuration Files |
| 193 | + |
| 194 | +``` |
| 195 | +~/.config/zellij/ |
| 196 | +├── config.kdl # Main configuration |
| 197 | +├── layouts/ |
| 198 | +│ └── tenseley.kdl # Custom layout with zjstatus |
| 199 | +├── themes/ |
| 200 | +│ └── tenseley.kdl # Tmux-inspired color theme |
| 201 | +└── plugins/ |
| 202 | + └── zjstatus.wasm # Custom status bar plugin |
| 203 | +``` |
| 204 | + |
| 205 | +## Layout Structure |
| 206 | + |
| 207 | +Current layout (`tenseley`): |
| 208 | +- **Top**: Default Zellij tab bar |
| 209 | +- **Middle**: Content panes |
| 210 | +- **Bottom**: zjstatus (session, hostname, mode, datetime) |
| 211 | + |
| 212 | +## Theme Colors |
| 213 | + |
| 214 | +| Element | Color | Hex | |
| 215 | +|---------|-------|-----| |
| 216 | +| Active border/accent | Green | `#7bd88f` | |
| 217 | +| Inactive border | Muted gray | `#4a5162` | |
| 218 | +| Main text | Light gray | `#b8c0cc` | |
| 219 | +| Muted text | Gray | `#8b94a6` | |
| 220 | +| Alert/error | Red | `#e05f5f` | |
| 221 | +| Background | Dark | `#1f2430` | |
| 222 | + |
| 223 | +## Tips & Workflows |
| 224 | + |
| 225 | +**Quick pane creation:** |
| 226 | +- `Alt n` creates a new pane instantly (no mode switch needed) |
| 227 | +- `Alt f` toggles floating panes for temporary work |
| 228 | + |
| 229 | +**Tmux muscle memory:** |
| 230 | +- `Ctrl Space` or `Ctrl b` enters tmux mode |
| 231 | +- Most tmux bindings work: `%`, `"`, `c`, `n`, `p`, `x`, `z`, `d` |
| 232 | + |
| 233 | +**Session management:** |
| 234 | +- `Ctrl o` then `w` opens session manager |
| 235 | +- Sessions auto-serialize for resurrection |
| 236 | + |
| 237 | +**Passthrough mode:** |
| 238 | +- `Ctrl g` locks Zellij, passing all keys to the terminal |
| 239 | +- Useful for nested multiplexers or apps with conflicting binds |
| 240 | + |
| 241 | +**Layouts:** |
| 242 | +- `Alt [` / `Alt ]` cycles through layout presets |
| 243 | +- `space` in tmux mode also cycles layouts |
| 244 | + |
| 245 | +## Differences from Tmux |
| 246 | + |
| 247 | +| Feature | Tmux | Zellij | |
| 248 | +|---------|------|--------| |
| 249 | +| Prefix | Single key then command | Modal (stay in mode) or tmux-style | |
| 250 | +| Plugins | TPM + shell scripts | WebAssembly (WASM) | |
| 251 | +| Config format | Shell-like | KDL | |
| 252 | +| Session restore | tmux-resurrect plugin | Built-in | |
| 253 | +| Floating panes | tmux-popup | Native | |
| 254 | +| Stacked panes | N/A | Native | |