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

Status Open

Maintainer reply None cached

Activity 3 comments · opened Mar 7, 2026

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:

Agent Teams: Use Zellij as an alternative to tmux for spawning teammate processes (tabs/panes instead of tmux sessions)
/terminal-setup: Add Zellij to the list of supported terminals (currently: iTerm2, WezTerm, Ghostty, Kitty, Alacritty, Zed, Warp)
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

View original on GitHub ↗

3 Comments

braininahat · 5 months ago

+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 · 5 months ago

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

matthiasdebernardini · 1 month ago

+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.