zellij
Use when editing ANY zellij configuration including layouts, swap layouts, keybindings, or zjstatus plugin. Provides rules for powerline characters, VHS testing, and verification.
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for managing and automating Zellij terminal multiplexer configurations. It streamlines the editing of layouts, keybindings, and plugins while ensuring visual consistency through automated VHS testing and specialized handling of powerline characters for a professional terminal environment.
Use Cases
- Automated Layout Customization: Effortlessly modify Zellij layouts and swap layouts using placeholders for powerline symbols, with an integrated converter to handle complex unicode characters.
- Isolated Visual Verification: Run automated UI tests using VHS in a dedicated session to verify terminal appearance changes without disrupting the user's active workspace.
- Standardized Theme Implementation: Apply consistent color schemes like Catppuccin Mocha and enforce specific UI rules for status bars and tab transitions to maintain a cohesive developer experience.
- Plugin and Keybinding Management: Safely edit zjstatus plugin configurations and keybindings within a dotfiles repository structure with built-in verification checklists.
| name | zellij |
|---|---|
| description | Use when editing ANY zellij configuration including layouts, swap layouts, keybindings, or zjstatus plugin. Provides rules for powerline characters, VHS testing, and verification. |
Zellij Skill
Configuration Locations
- Layout files:
home/.config/zellij/layouts/ - Plugin file:
home/.config/zellij/plugins/zjstatus.wasm - Always edit files in the dotfiles repo, not symlinked files in
~/.config/
Powerline Characters
Claude Code strips unicode characters. Use placeholders in the layout file (layout.kdl in this skill folder):
{{PL_RIGHT}}- right-pointing arrow (U+E0B0){{PL_LEFT}}- left-pointing arrow (U+E0B2)
After editing the layout, run the converter:
.claude/skills/zellij/convert-layout
This reads layout.kdl from the skill folder, replaces placeholders with actual powerline chars, and writes to ~/.config/zellij/layouts/layout.kdl.
VHS Testing
CRITICAL: NEVER run zellij commands in the user's active session. VHS creates its own isolated terminal.
CRITICAL: ALWAYS use the tapes in this skill folder. NEVER create ad-hoc tape files with different output names.
Use VHS to verify visual changes:
- Delete any existing test session:
zellij delete-session zellij-test - Run the appropriate tape from
.claude/skills/zellij/:layout.tape- Tests tabs and zjstatus bar appearanceswap-layout.tape- Tests swap layouts with multiple panes (creates 3 panes, cycles through layouts)
- Output screenshot ALWAYS goes to
tmp/zellij.png(same name, no versioning) - Read the screenshot to verify before telling user the fix is complete
- Clean up the test session:
zellij delete-session zellij-test
The tapes create a dedicated zellij-test session. Never use zellij action commands directly - they affect the user's current session.
Color Scheme
Use Catppuccin Mocha colors. Reference by name in requirements:
- base, surface1, lavender, text (not hex codes)
Top Bar Layout
- Session name, tabs with powerline arrows, hostname/username
- Arrows between tabs use base color as foreground
- Active tab: accent background, base text color
- Inactive tabs: surface background, text color
Bottom Bar Layout
- Mode indicator, active tab name only, datetime
- Show only active tab name (no inactive tabs)
Verification Checklist
Before declaring complete, verify:
- Top bar arrows use dark/base color between all tabs
- No accent color triangles between inactive tabs
- Bottom bar shows only active tab name
- Bottom bar has no powerline triangles
- Session name arrow transitions correctly to first tab