Zellij Session Control

This skill enables remote interaction with existing zellij terminal sessions -- capturing screen output, sending keystrokes, and managing panes without direct TTY access.

Listing Sessions

# List all active sessions (parseable output)
zellij list-sessions --no-formatting

# Just session names
zellij list-sessions --short

# Filter to only active (non-exited) sessions
zellij list-sessions --no-formatting | grep -v EXITED

Targeting a Session

All actions target a session using the -s flag on the top-level zellij command (NOT on the action subcommand):

zellij -s SESSION_NAME action <subcommand>

Capturing Screen Output ("Screenshots")

# Dump focused pane to a file (text content, not pixels)
zellij -s SESSION_NAME action dump-screen /tmp/zellij-capture.txt

# Dump with full scrollback history
zellij -s SESSION_NAME action dump-screen --full /tmp/zellij-capture.txt

# Then read the captured output
cat /tmp/zellij-capture.txt

Note: dump-screen captures the focused pane only. To capture other panes, first switch focus (see Pane Navigation below).

Sending Keystrokes

# Send literal text characters
zellij -s SESSION_NAME action write-chars "ls -la"

# Send Enter key (byte 13 = carriage return)
zellij -s SESSION_NAME action write 13

# Send a command and press Enter (two steps)
zellij -s SESSION_NAME action write-chars "make build"
zellij -s SESSION_NAME action write 13

# Send Escape (byte 27)
zellij -s SESSION_NAME action write 27

# Send Ctrl+C (byte 3)
zellij -s SESSION_NAME action write 3

# Send Ctrl+D / EOF (byte 4)
zellij -s SESSION_NAME action write 4

# Send Ctrl+Z / suspend (byte 26)
zellij -s SESSION_NAME action write 26

# Send Tab (byte 9)
zellij -s SESSION_NAME action write 9

Common Control Byte Reference

Arrow Keys (ANSI escape sequences)

# Up arrow: ESC [ A
zellij -s SESSION_NAME action write 27 91 65

# Down arrow: ESC [ B
zellij -s SESSION_NAME action write 27 91 66

# Right arrow: ESC [ C
zellij -s SESSION_NAME action write 27 91 67

# Left arrow: ESC [ D
zellij -s SESSION_NAME action write 27 91 68

Pane Navigation

# Move focus between panes
zellij -s SESSION_NAME action focus-next-pane
zellij -s SESSION_NAME action focus-previous-pane
zellij -s SESSION_NAME action move-focus right   # right|left|up|down

# Toggle fullscreen on focused pane
zellij -s SESSION_NAME action toggle-fullscreen

Tab Navigation

# Switch tabs
zellij -s SESSION_NAME action go-to-tab 1          # by index (1-based)
zellij -s SESSION_NAME action go-to-tab-name "dev"  # by name
zellij -s SESSION_NAME action go-to-next-tab
zellij -s SESSION_NAME action go-to-previous-tab

# Query tab names
zellij -s SESSION_NAME action query-tab-names

Scrolling

zellij -s SESSION_NAME action scroll-up
zellij -s SESSION_NAME action scroll-down
zellij -s SESSION_NAME action scroll-to-top
zellij -s SESSION_NAME action scroll-to-bottom
zellij -s SESSION_NAME action half-page-scroll-up
zellij -s SESSION_NAME action half-page-scroll-down

Session Management

# Kill a session
zellij kill-session SESSION_NAME

# Kill all sessions
zellij kill-all-sessions

# Delete exited sessions
zellij delete-session SESSION_NAME
zellij delete-all-sessions

# Rename current session
zellij -s SESSION_NAME action rename-session "new-name"

Pane and Tab Management

# Close focused pane or tab
zellij -s SESSION_NAME action close-pane
zellij -s SESSION_NAME action close-tab

# Rename focused pane or tab
zellij -s SESSION_NAME action rename-pane "my-pane"
zellij -s SESSION_NAME action rename-tab "my-tab"

# Clear pane buffer
zellij -s SESSION_NAME action clear

# Dump current layout
zellij -s SESSION_NAME action dump-layout

Complete Workflow: Observe and Interact

# 1. Find active sessions
zellij list-sessions --no-formatting | grep -v EXITED

# 2. Capture current screen
zellij -s myapp action dump-screen /tmp/screen.txt
cat /tmp/screen.txt

# 3. Send a command
zellij -s myapp action write-chars "cargo test"
zellij -s myapp action write 13

# 4. Wait and capture result
sleep 3
zellij -s myapp action dump-screen /tmp/result.txt
cat /tmp/result.txt

Rapid Snapshots (for TUI Debugging)

# Take multiple snapshots at intervals to observe state changes
for i in $(seq 1 10); do
  echo "=== SNAPSHOT $i ($(date +%H:%M:%S.%3N)) ==="
  zellij -s SESSION_NAME action dump-screen /tmp/snap_$i.txt
  cat /tmp/snap_$i.txt
  echo ""
  sleep 0.2
done

Troubleshooting

"Session not found": The session may be EXITED. Use zellij list-sessions --no-formatting to check status. Only active (non-exited) sessions accept actions.

Wrong pane captured: dump-screen captures the focused pane. Use focus-next-pane or move-focus to change which pane is focused before capturing.

No send-keys equivalent: Unlike tmux, zellij has no named-key send-keys. Use write-chars for text and write with byte values for control keys and escape sequences.