Agent Teams: Add zellij terminal multiplexer support for split-pane mode
Feature Request
Agent Teams currently supports split-pane mode for tmux and iTerm2, automatically opening each teammate in its own pane. Zellij — a modern terminal multiplexer growing in popularity — has no integration, forcing users to fall back to in-process mode.
Why
Zellij is increasingly adopted as a tmux alternative due to its discoverability, sane defaults, and native floating panes. Users running Claude Code inside zellij should get the same split-pane experience as tmux users.
Implementation Guide
Zellij exposes everything needed via zellij action CLI commands, analogous to how tmux uses tmux split-window / tmux send-keys.
Detection
Zellij sets environment variables when running inside a session:
ZELLIJ=0 # Present when inside zellij
ZELLIJ_SESSION_NAME=work # Current session name
ZELLIJ_PANE_ID=3 # Current pane IDDetection is simply: process.env.ZELLIJ !== undefined
This mirrors the existing tmux detection (TMUX env var).
Spawning a teammate pane
# Split right with a command, named after the agent
zellij action new-pane \
--direction right \
--name "researcher" \
-- claude --teammate-mode in-process ...
# Or split down
zellij action new-pane \
--direction down \
--name "implementer" \
-- claude ...Key flags:
--direction right|down— controls split direction (liketmux split-window -h/-v)--name <NAME>— labels the pane (visible in zellij UI, no need for a separate rename step)--close-on-exit— auto-close pane when agent finishes (optional)--cwd <DIR>— set working directory-- <COMMAND>...— the command to run in the new pane
Alternative: new tab per agent
zellij action new-tab --name "researcher"
# Then the command runs in that tabAlternative: floating panes (unique to zellij)
zellij action new-pane \
--floating \
--name "researcher" \
--width 50% --height 50% \
-- claude ...This has no tmux equivalent and could be a zellij-specific bonus feature.
Writing to a pane
zellij action write-chars "some input" # Types into the focused paneMapping to existing tmux integration
| tmux command | zellij equivalent |
|---|---|
| tmux split-window -h cmd | zellij action new-pane -d right -- cmd |
| tmux split-window -v cmd | zellij action new-pane -d down -- cmd |
| tmux send-keys "text" Enter | zellij action write-chars "text\n" |
| tmux select-pane -t N | zellij action focus-next-pane (or move-focus) |
| tmux rename-window "name" | --name flag on new-pane / new-tab |
| $TMUX detection | $ZELLIJ detection |
teammateMode setting
Add "zellij" as a valid value alongside "tmux", and update "auto" to detect $ZELLIJ:
auto priority: iTerm2 > tmux > zellij > in-processCurrent workaround
claude --teammate-mode in-processWorks but loses the multi-pane visibility that makes the teams feature compelling.
11 Comments
Found 1 possible duplicate issue:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Not a duplicate — #23574 is about WezTerm support, this is about Zellij support. Different terminal multiplexers with different CLIs and APIs.
I would think that zellij should take priority over tmux in auto mode, given tmux often comes preinstalled, but with zellij, you have to go out of your way to use it.
But otherwise, yes please!
+1 to zellij support; I was very surprised when I figured out that it's not supported yet
@kmelkon thanks for the detailed integration guide. I hope it helps speed up the process
I built a working shim for this: zellij-claude-teams
It's a fake
tmuxbinary that intercepts Claude Code's tmux calls and routes them throughzellij action. Agent teammates spawn as real zellij panes. Tested on Claude Code 2.1.63, works on macOS and Linux.A few things I ran into that would be relevant for native integration:
new-panestarts clean — so env vars likeCLAUDECODE,CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, etc. are lost. The shim snapshots the parent environment to a file and restores it in each new pane.write-chars. It only works on the currently focused pane — there's no--pane-idflag. Sotmux send-keys -t %3 "command"can't be translated directly. The shim uses a named pipe (FIFO) per pane instead: the pane process waits on its pipe, andsend-keyswrites the command there. This avoids any focus dependency.new-panealways steals focus. There's no--no-focusflag in zellij. The shim works around this by immediately runningmove-focusin the opposite direction to return focus to the original pane.split-window,send-keys,kill-pane,display-message,has-session). The rest — things likeselect-layout,resize-pane,set-option,break-pane— can safely return exit 0 without doing anything, since zellij handles layout automatically.Feel free to use the repo for inspiration or as a temporary workaround.
zellij is the best terminal multiplexer! (I'm a heavy tmux user for 8+ years and zellij user for 2+ years. I never regret). Please support zellij.
Yes, please! Native Zellij support would be fantastic.
+1
+1
+1, Native Zellij support would be amazing.
+1
+1 as another zellij user. The conceptual lift looks small:
zellij action new-pane -- <cmd>maps almost one-to-one onto what the tmux driver already does withsplit-window, and zellij detection is a single env-var check ($ZELLIJ) exactly like$TMUX. So this reads more like adding a third pane-spawn driver alongside the existing tmux/iTerm2 ones than a from-scratch integration — in line with the implementation guide above.