zellij Skill (Moltbot)

Use zellij only when you need an interactive TTY. Prefer exec background mode for long-running, non-interactive tasks.

Quickstart (data dir, exec tool)

DATA_DIR="${CLAWDBOT_ZELLIJ_DATA_DIR:-${TMPDIR:-/tmp}/moltbot-zellij-data}"
mkdir -p "$DATA_DIR"
SESSION=moltbot-python

zellij --data-dir "$DATA_DIR" new-session --session "$SESSION" --layout "default" --detach
zellij --data-dir "$DATA_DIR" run --session "$SESSION" --name repl -- python3 -q
zellij --data-dir "$DATA_DIR" pipe --session "$SESSION" --pane-id 0

After starting a session, always print monitor commands:

To monitor:
  zellij --data-dir "$DATA_DIR" attach --session "$SESSION"
  zellij --data-dir "$DATA_DIR" pipe --session "$SESSION" --pane-id 0

Data directory convention

• Use CLAWDBOT_ZELLIJ_DATA_DIR (default ${TMPDIR:-/tmp}/moltbot-zellij-data).
• Zellij stores state (sessions, plugins, etc.) in this directory.

Targeting panes and naming

• Zellij uses pane-id (numeric) to target specific panes.
• Find pane IDs: zellij --data-dir "$DATA_DIR" list-sessions --long or use list-panes.sh.
• Keep session names short; avoid spaces.

Finding sessions

• List sessions on your data dir: zellij --data-dir "$DATA_DIR" list-sessions.
• List sessions across all data dirs: {baseDir}/scripts/find-sessions.sh --all (uses CLAWDBOT_ZELLIJ_DATA_DIR).

Sending input safely

• Use zellij action to send keystrokes: zellij --data-dir "$DATA_DIR" action --session "$SESSION" write-chars --chars "$cmd".
• Control keys: zellij --data-dir "$DATA_DIR" action --session "$SESSION" write 2 (Ctrl+C).

Watching output

• Capture pane output: zellij --data-dir "$DATA_DIR" pipe --session "$SESSION" --pane-id 0.
• Wait for prompts: {baseDir}/scripts/wait-for-text.sh -s "$SESSION" -p 0 -p 'pattern'.
• Attaching is OK; detach with Ctrl+p d (zellij default detach).

Spawning processes

• For python REPLs, zellij works well with standard python3 -q.
• No special flags needed like tmux's PYTHON_BASIC_REPL=1.

Windows / WSL

• zellij is supported on macOS/Linux. On Windows, use WSL and install zellij inside WSL.
• This skill is gated to darwin/linux and requires zellij on PATH.

Orchestrating Coding Agents (Codex, Claude Code)

zellij excels at running multiple coding agents in parallel:

DATA_DIR="${TMPDIR:-/tmp}/codex-army-data"

# Create multiple sessions
for i in 1 2 3 4 5; do
  zellij --data-dir "$DATA_DIR" new-session --session "agent-$i" --layout "compact" --detach
done

# Launch agents in different workdirs
zellij --data-dir "$DATA_DIR" action --session "agent-1" write-chars --chars "cd /tmp/project1 && codex --yolo 'Fix bug X'\n"
zellij --data-dir "$DATA_DIR" action --session "agent-2" write-chars --chars "cd /tmp/project2 && codex --yolo 'Fix bug Y'\n"

# Poll for completion (check if prompt returned)
for sess in agent-1 agent-2; do
  pane_id=$(zellij --data-dir "$DATA_DIR" list-sessions --long | grep "\"$sess\"" | jq -r '.tabs[0].panes[0].id')
  if zellij --data-dir "$DATA_DIR" pipe --session "$sess" --pane-id "$pane_id" | grep -q "❯"; then
    echo "$sess: DONE"
  else
    echo "$sess: Running..."
  fi
done

# Get full output from completed session
zellij --data-dir "$DATA_DIR" pipe --session "agent-1" --pane-id 0

Tips:

• Use separate git worktrees for parallel fixes (no branch conflicts)
• pnpm install first before running codex in fresh clones
• Check for shell prompt (❯ or $) to detect completion
• Codex needs --yolo or --full-auto for non-interactive fixes

Cleanup

• Kill a session: zellij --data-dir "$DATA_DIR" delete-session --session "$SESSION".
• Kill all sessions on a data dir: use {baseDir}/scripts/cleanup-sessions.sh "$DATA_DIR".

Zellij vs Tmux Quick Reference

Helper: wait-for-text.sh

{baseDir}/scripts/wait-for-text.sh polls a pane for a regex (or fixed string) with a timeout.

{baseDir}/scripts/wait-for-text.sh -s session -p pane-id -r 'pattern' [-F] [-T 20] [-i 0.5]

• -s/--session session name (required)
• -p/--pane-id pane ID (required)
• -r/--pattern regex to match (required); add -F for fixed string
• -T timeout seconds (integer, default 15)
• -i poll interval seconds (default 0.5)

Helper: find-panes.sh

{baseDir}/scripts/find-panes.sh lists panes for a given session.

{baseDir}/scripts/find-panes.sh -s session [-d data-dir]

• -s/--session session name (required)
• -d/--data-dir zellij data dir (uses CLAWDBOT_ZELLIJ_DATA_DIR if not specified)