Zellij Claude Teams

zellij-claude-teams

Use [Claude Code](https://docs.anthropic.com/en/docs/claude-code) **Agent Teams** inside [Zellij](https://zellij.dev) — no tmux required.

The Problem

Claude Code's Agent Teams feature spawns each teammate in its own terminal pane using **tmux**. If you use Zellij as your terminal multiplexer, Agent Teams silently falls back to in-process mode — no split panes, no visual separation.

The Solution

This project provides a **tmux shim** — a fake `tmux` binary that intercepts Claude Code's tmux commands and translates them to `zellij action` equivalents. Agent teammates spawn as real Zellij panes within your current tab.

┌──────────────────────┬──────────────────────┐
│                      │  researcher          │
│   Claude Code        ├──────────────────────┤
│   (your session)     │  implementer         │
│                      ├──────────────────────┤
│                      │  tester              │
└──────────────────────┴──────────────────────┘

Agent panes are named after their role and stack vertically on the right.

Requirements

• Zellij 0.40+ (tested on 0.43.1)
• Bash 3.2+ (ships with macOS; Linux has 4+)
• Claude Code with Agent Teams support

Installation

git clone https://github.com/stanislc/zellij-claude-teams.git
cd zellij-claude-teams
bash install.sh

The install script copies files to `${XDG_DATA_HOME:-~/.local/share}/zellij-tmux-shim/` and prints the activation snippet for your shell.

Shell activation

Add **one** of these to your shell config:

**Bash** (`~/.bashrc`):

if [ -n "$ZELLIJ" ]; then
    _shim="${XDG_DATA_HOME:-$HOME/.local/share}/zellij-tmux-shim/activate.sh"
    [ -f "$_shim" ] && . "$_shim"
    unset _shim
fi

**Zsh** (`~/.zshrc`):

if [[ -n "$ZELLIJ" ]]; then
    _shim="${XDG_DATA_HOME:-$HOME/.local/share}/zellij-tmux-shim/activate.sh"
    [[ -f "$_shim" ]] && source "$_shim"
    unset _shim
fi

Then restart your shell inside Zellij.

W