Zellij Helper

Zellij Helper

Use layouts for declarative session structure and explicit session-targeted CLI actions for automation. Keep CLI subcommands separate from KDL keybinding actions, and treat resurrection, web access, plugins, and screen dumps as security boundaries.

Current baseline

Verified against Zellij 0.44.3 on 2026-08-03:

zellij --version

Zellij 0.44 added native Windows support, Layout Manager, remote HTTPS attachment, read-only sharing tokens, richer automation and subscription APIs, and a new Wasm runtime. 0.44.1 added layout strings and more pane targeting; 0.44.2 added automatic light/dark themes; 0.44.3 fixed host-query forwarding regressions.

Read references/releases.md for the 57-page research ledger. Read references/cli-and-layouts.md for current CLI automation and KDL. Read references/configuration-and-resurrection.md for keybindings, serialization, themes, and recovery. Read references/plugins-and-web-security.md for Wasm permissions, pipes, web sharing, tokens, TLS, and sensitive output.

Sessions

List machine-readable names instead of parsing decorated output:

zellij list-sessions --short --no-formatting

Use exact fixed-string matching for user-selected session names. Regex interpolation makes metacharacters meaningful and can select the wrong session.

Create a detached/background session for automation:

zellij attach --create-background development

Target every scripted action explicitly:

zellij --session development action new-pane --cwd "$PWD"

Bare actions outside a session can be ambiguous when several sessions exist. Prefer returned pane/tab IDs and JSON from list-panes / list-tabs when subsequent steps depend on created resources.

Current CLI syntax

zellij action move-pane left
zellij action resize increase left
zellij action dump-screen --path /private/output/screen.txt
zellij action write-chars 'echo hello'
zellij action send-keys 'ENTER'
zellij action stack-panes -- terminal_1 plugin_2 3

• Direction for move-pane is positional.
• Resize takes increase/decrease and an optional direction, not a numeric amount.
• dump-screen requires --path and can target panes/full scrollback/ANSI.
• write accepts integer bytes; use write-chars or send-keys for readable input.
• stack-panes takes explicit pane IDs and is not directional.

Actions such as Quit, ToggleTab, and some break-pane forms exist in KDL keybindings but are not automatically zellij action CLI subcommands. Check the CLI reference before translating between APIs.

Run and edit panes

--in-place suspends and temporarily replaces the current pane. Add --close-replaced-pane only when permanent replacement is intended.

For automation, use blocking run modes or returned pane IDs instead of starting an attached client in the background and sleeping. Avoid timing races and untargeted actions.

Layouts

Percentage KDL coordinates are strings:

floating_pane x="10%" y="10%" width="80%" height="80%"

Session options belong at the document root, not in a session node:

session_name "development"
attach_to_session true

layout {
    tab name="editor" {
        pane command="nvim"
    }
}

Relative cwd values compose through pane, tab, global layout, and invocation directory. Loading a layout from inside a session adds tabs; use the current new-session-with-layout option when a separate session is required.

zellij setup --dump-config prints the shipped default config, not the current effective configuration. Zellij 0.44.3 has no layout --dry-run flag.

Configuration and keybindings

Do not combine clear-defaults=true with an incomplete map. It removes omitted bindings across modes and can trap users in rename/search/move/tmux modes. Retain defaults and selectively unbind, or define every used mode and escape path.

mirror_session controls whether clients attached to one session share cursor/view state; it does not synchronize pane input. Synchronize pane input with zellij action toggle-active-sync-tab.

Current nested session-name hiding:

ui {
    pane_frames {
        hide_session_name true
    }
}

Theme names include iceberg-dark and iceberg-light. Current options also include dark/light theme selection, serialization interval, metadata controls, default CWD, OSC 8 hyperlinks, mouse behavior, session attach/name, and web sharing.