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)
