Zellij Terminal Workspace

Remote-control zellij sessions for interactive CLIs by sending keystrokes and scraping pane output.

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

Task	tmux	zellij
List sessions	list-sessions	list-sessions
Create session	new-session -d	new-session --detach
Attach	attach -t	attach --session
Send keys	send-keys	action write-chars
Capture pane	capture-pane	pipe
Kill session	kill-session	delete-session
Detach	Ctrl+b d	Ctrl+p d

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)