Feature request: Native Zellij support as alternative to tmux for Agent Teams and /terminal-setup

[dapi]

Summary

Claude Code currently uses tmux as the only supported terminal multiplexer for Agent Teams (v2.1.32+) and does not include Zellij in /terminal-setup. Zellij is a modern terminal multiplexer written in Rust with a growing user base and a rich plugin ecosystem.

I'd like to request native Zellij support in Claude Code, specifically:

1. Agent Teams: Use Zellij as an alternative to tmux for spawning teammate processes (tabs/panes instead of tmux sessions)
2. /terminal-setup: Add Zellij to the list of supported terminals (currently: iTerm2, WezTerm, Ghostty, Kitty, Alacritty, Zed, Warp)
3. Shift+Enter / keyboard protocol: Zellij supports the Kitty keyboard protocol — ensure proper key handling

Why Zellij?

• Modern architecture: Written in Rust, WebAssembly plugin system, built-in layout engine
• Growing adoption: Active development, strong community, native floating panes
• Rich CLI: zellij action new-tab, zellij run, zellij action write-chars — all scriptable, suitable for agent orchestration
• Session management: Named sessions, tab renaming, plugin-driven status indicators

Existing community work

I maintain a Claude Code plugin zellij-workflow (v1.4.3, MIT license) that provides Zellij integration today:

Features

• Tab/pane management: Create tabs and panes — empty, with shell commands, with Claude sessions, or for GitHub issue development
• Tab status indicators: Show Claude session state via icon prefix in tab name (○ Ready, ◉ Working, ✋ Needs input, ◌ Compacting) using a companion Zellij WASM plugin zellij-tab-status
• Hooks integration: PreToolUse/PostToolUse/Stop hooks update tab status in real-time
• Cross-shell compatibility: Works with bash, zsh, and fish via script-based launching

Commands & Skills

Component	Description
/run-in-new-tab	Launch Claude session or command in a new Zellij tab
/start-issue-in-new-tab	Start GitHub issue development in a new tab
zellij-tab-pane skill	Universal trigger for tab/pane operations

Install

/plugin install zellij-workflow@dapi

This plugin demonstrates that Zellij's CLI is well-suited for agent orchestration and could serve as a reference for native integration.

Proposed approach

For Agent Teams specifically:

• Detect $ZELLIJ environment variable (similar to how tmux detection works via $TMUX)
• Use zellij action new-tab --name <agent> + zellij action write-chars to spawn teammates
• Use zellij run -- for isolated command execution in panes
• Leverage Zellij's plugin system for richer status reporting (optional)

Environment

• Zellij 0.41+ (current stable)
• Claude Code 2.1.x
• Linux / macOS

[braininahat]

+1 from a heavy agent teams user. Running 5-7 specialist agents in tmux split-pane mode — the layout management is painful. tmux's custom layout strings require manual checksum computation (select-layout rejects invalid checksums), and there's no way to express "1 main column + 2×3 grid" without fighting the layout engine for 10 minutes.

Zellij's KDL layout files would solve this cleanly:

layout {
    pane size="33%" // me
    pane split_direction="vertical" {
        pane // agent 1
        pane // agent 2  
        pane // agent 3
    }
    pane split_direction="vertical" {
        pane // agent 4
        pane // agent 5
        pane // agent 6
    }
}

Named panes, floating panes for monitoring, and native layout persistence would make agent teams significantly more usable on Linux workstations. Currently using --teammate-mode auto with tmux but would switch to zellij immediately if supported.

[discohead]

@braininahat This works pretty well: https://github.com/stanislc/zellij-claude-teams

[matthiasdebernardini]

+1 — for Ghostty users this isn't a convenience request, it's the only path to split-pane teams. The docs list Ghostty as unsupported for split-pane mode, and tmux-inside-Ghostty is exactly what Zellij users switched away from. I run Claude Code daily across ~10 client repos in one Zellij session, so Agent Teams falling back to in-process mode loses the feature's main value for me.

I got split panes working today via the shim @discohead linked (stanislc/zellij-claude-teams), and it works — but the lengths it has to go to are the best argument for native support:

• It fakes $TMUX / $TMUX_PANE so Claude Code will even attempt split-pane mode, because teammate display only probes for tmux/iTerm2.
• zellij action new-pane doesn't inherit the parent env (unlike tmux), so it snapshots the environment via export -p and evals it back inside a pane wrapper.
• Emulating send-keys requires a FIFO (named pipe) per pane plus sentinel files, and mkdir-based locking because macOS has no flock.
• Its README lists "fragile to Claude Code updates" as a known limitation — any new tmux command upstream silently breaks teammates for every Zellij user.

Meanwhile the actual surface area is small, as the OP outlined: detect $ZELLIJ, then zellij action new-pane / rename-pane / write-chars, with --close-on-exit handling teardown. The shim is basically two shell scripts proving the whole feature already works cleanly in Zellij — native support would mostly be deleting workarounds rather than building a new backend.

Between 53 👍, dapi's zellij-workflow plugin, and this shim, the community has now independently built Zellij integration twice. Would love to see it land as a supported teammateMode target.