ryanmaclean Zellij Team — Parallel Claude Agents in Zellij Panes
Overview
Spawn N parallel claude workers, each in its own Zellij pane, so you can
watch them work simultaneously and ctrl-c any pane to kill a runaway agent.
This is the Zellij-native equivalent of Claude Code's tmux agent teams backend. The current session is the team leader. Workers are spawned with explicit task prompts and run until they exit or you kill them.
Quick Start
# Spawn 3 agents on explicit tasks
nu ~/.claude/skills/zellij-team/zellij-team.nu \
--tasks ["Fix the auth bug in src/auth.ex" \
"Write tests for ElixirGastown.LLM.RateLimiter" \
"Update README with new rate-limiter docs"]
# Spawn from task files
nu ~/.claude/skills/zellij-team/zellij-team.nu \
--files [tasks/auth-fix.md tasks/test-rate-limiter.md tasks/docs.md]
# Custom session / tab name
nu ~/.claude/skills/zellij-team/zellij-team.nu \
--tab "gas-city-workers" \
--tasks ["task A" "task B"]
Interaction Model
| Action | How |
|---|---|
| Watch agents | Look at each pane — they stream output live |
| Kill one agent | ctrl-c in that pane |
| Kill all | Close the Zellij tab |
| Switch panes | Alt+arrow |
| Zoom a pane | ctrl-p z |
| Send input to agent | Click pane, type (only if agent paused at a question) |
Layout
Workers open in a new tab in the current Zellij session, auto-split:
- 2 workers → side by side (vertical split)
- 3–4 workers → 2×2 grid
- 5–6 workers → 2 rows, 3 cols
- 7+ workers → 3 rows
The tab is named team-<timestamp> by default, or --tab NAME.
Agent Flags Used
Workers run with:
claude --dangerously-skip-permissions --permission-mode bypassPermissions
Rationale: workers are short-lived, task-scoped subprocesses. You (the leader) are watching and can ctrl-c. Full interactive permission prompts would stall them.
Override with --mode default if you want workers to prompt for permissions.
Token Efficiency
Each worker has its own context window. Keep task prompts focused:
- Good: "Fix the 3 failing tests in test/rate_limiter_test.exs"
- Bad: "You are an expert engineer, please consider all aspects of..."
Use --effort low on workers for routine tasks, high only for complex ones.
Key Rule: Never Hardcode Session Name
Uses $ZELLIJ_SESSION_NAME — see zellij skill for the canonical pattern.