@@ -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 | |