Zellij

Quick Reference

Sessions

Tabs

Panes

Run Commands in Panes

Edit Files in Panes

Programmatic Control

Sending Text to Panes

# Send text to focused pane (no execution)
zellij action write-chars "some text"

# Send command with Enter to execute
zellij action write-chars $'echo hello\n'

# Send to specific session
zellij -s my-session action write-chars $'cargo test\n'

# Send control characters
zellij action write 3      # Ctrl+C
zellij action write 4      # Ctrl+D
zellij action write 27     # Escape

Capturing Pane Output

# Dump visible pane content to file
zellij action dump-screen /tmp/output.txt

# Dump with full scrollback history
zellij action dump-screen --full /tmp/output.txt

# Dump current layout (useful for saving/sharing)
zellij action dump-layout

Switch Modes Programmatically

zellij action switch-mode locked    # Pass-through mode
zellij action switch-mode normal    # Back to normal

Common Patterns

New tab for specific task:

zellij action new-tab --name "backend" --cwd ~/api

Split pane and run command:

zellij action new-pane --direction down -- npm run dev

New pane with guaranteed working directory:

# For interactive shell with specific directory
zellij action new-pane --cwd /path/to/dir

# For command that must run in specific directory
zellij action new-pane --cwd /path/to/dir -- sh -c 'cd /path/to/dir && your-command'

# For nvim that must start in specific directory
zellij action new-pane --cwd /path/to/worktree -- sh -c 'cd /path/to/worktree && nvim'

Floating scratch terminal:

zellij action new-pane --floating --width 90% --height 90%

Run parallel agents in separate sessions:

# Create detached sessions
zellij attach -b agent-1
zellij attach -b agent-2

# Send commands to each
zellij -s agent-1 action write-chars $'cd /tmp/project1 && codex "Fix bug X"\n'
zellij -s agent-2 action write-chars $'cd /tmp/project2 && codex "Fix bug Y"\n'

# Check output
zellij -s agent-1 action dump-screen /tmp/agent1-output.txt

Session Resurrection

Zellij auto-saves session state. Exited sessions can be resurrected:

zellij ls                                  # Shows EXITED sessions
zellij attach <exited-session>             # Resurrect it
zellij attach <name> --force-run-commands  # Skip "Press ENTER" confirmation
zellij delete-session <name>               # Permanently remove

Setup Utilities

zellij setup --dump-config                # Print default config
zellij setup --dump-layout default        # Print default layout
zellij setup --dump-layout compact        # Print compact layout
zellij setup --generate-completion fish   # Fish completions
zellij setup --check                      # Validate config

Environment Variables

Common Mistakes

Wrong: Using new-pane --horizontal Correct: --direction down (not --horizontal)

Wrong: Confusing toggle with create

• toggle-floating-panes = show/hide existing floating panes
• new-pane --floating = create NEW floating pane

Wrong: Forgetting action subcommand zellij new-tab -> zellij action new-tab

Wrong: Pane not starting in correct directory Using --cwd alone doesn't always ensure the command runs in that directory:

# Wrong - nvim might not start in the right directory
zellij action new-pane --cwd /path -- nvim

# Correct - explicitly cd first
zellij action new-pane --cwd /path -- sh -c 'cd /path && nvim'

Wrong: Text not appearing in target pane

• Ensure the target pane is focused
• Try switching to normal mode first: zellij action switch-mode normal
• Remember to include newline for execution: $'command\n'

Notes

• All zellij action commands work inside or outside a session
• Use -- to separate pane command from zellij options
• Direction options: right, left, up, down
• Size units: bare integers or percentages (e.g., 80%)
• Hold SHIFT to bypass Zellij mouse capture for terminal selection
• Use -s <session> flag to target specific sessions when automating