Claude Media
Claude Code Agent TeamsはZellijに未対応 — 現状と回避策
Claude CodeTips

Claude Code Agent TeamsはZellijに未対応 — 現状と回避策

Agent Teamsのsplit-paneが対応するのはtmuxとiTerm2だけで、Zellijは2026年3月からfeature requestのままです。ZellijでのふるまいとシムのしくみをIssueから読み解きます。

読了目安 約8分

Zellijでは何が起きるか

Agent Teamsのsplit-pane表示が使えるのは、tmuxとiTerm2(it2 CLI付き)です。Zellijでのsplit-pane対応は、2026年3月7日に立てられたfeature requestのまま進んでいません。

Claude CodeをZellij内で使うとき、Agent Teamsはin-processで動きます。in-processはどの端末でも動くと公式にあります。teammateは専用ペインではなく、メインターミナルのエージェントパネルに並びます。このほか、in-process特有の制約があります(後述)。

くらべる

Zellijで選べる3つの使い方

設定不要

in-processのまま使う

既定の表示です。上下矢印でteammateを選び、Enterでやり取りします。どの端末でも動きます。再開やバックグラウンドのsubagentには制約があります。

公式対応

tmuxセッションで使う

split-pane表示を使いたいときの公式の経路です。ZellijをやめてtmuxかiTerm2に移ります。

コミュニティ製

シムで偽装する

tmuxのふりをさせてZellij上でsplit-paneを出す非公式の方法です。Claude Codeの更新で壊れる前提で使います。

split-paneが出ない理由はteammateModeの仕様にある

表示モードはteammateModeで決まります。値は4つあり、Zellijに関わるのは判定の条件です。

値split-paneになる条件
in-process(既定)split-paneになる条件ならない。どの端末でも動く
autosplit-paneになる条件tmuxの中で起動したとき、またはiTerm2でit2がPATHにあるか、tmuxが入っているとき
tmuxsplit-paneになる条件tmuxまたはiTerm2を端末から判定して使う
iterm2split-paneになる条件iTerm2のネイティブ分割(it2 CLI必須)

autoの条件にZellijはありません。Zellijセッションの中でautoにしても、その外側がtmuxでもiTerm2でもなければin-processで動きます。設定したのにペインが分かれないときは、まずこの条件を疑います。

条件の書き方はページごとにわずかに違います。Agent Teamsのページは「tmux、またはiTerm2でit2が入っている場合」、設定リファレンスは「iTerm2でit2がPATHにあるかtmuxが入っている場合」です。iTerm2を使う人だけに効く差です。

iTerm2のネイティブ対応は、v2.1.186(2026年6月22日)のteammateMode: "iterm2"で入りました。it2 CLIの導入と、iTerm2側のPython API有効化(Settings → General → Magic)が前提です。非対応の端末はVS Code統合ターミナル、Windows Terminal、Ghosttyと明記されています。

手元の確認(v2.1.287)

--teammate-modeフラグは、公式docsに「実験的でclaude --helpには出ない」とあります。v2.1.287の--helpを確かめると、teammateを含む行は0件でした。

claude --version
claude --help | grep -c -i teammate
2.1.287 (Claude Code)
0

フラグを一時的に試したいときはclaude --teammate-mode autoのように渡します。この値は設定ファイルのteammateModeより優先されます。

Agent Teamsの有効化とin-processの制約

Agent Teamsは実験的機能で、既定では無効です。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定ファイルか環境変数に入れないと、セッション開始時にチームが組まれません。Claudeはteammateを起動も提案もしません。ペインが分かれない原因を探す前に、まずここを見ます。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "teammateMode": "in-process"
}

in-processのteammateには、split-paneにない制約があります。/resumeと/rewindではteammateが復元されません。再開後にリードが、すでに存在しないteammateへメッセージを送ろうとすることがあります。teammateが起動するsubagentはフォアグラウンドで動きます。定義にbackground: trueがあるとエラーになります。

agent定義の扱いも違います。in-processでは定義の本文が既定のシステムプロンプトに追記され、mcpServers欄は無視されます。MCPサーバーはプロジェクトとユーザーの設定から読まれます。split-paneのteammateでは、本文が既定のプロンプトの代わりに使われます。

Zellijではペインが分かれないので、エージェントパネルがteammateへの窓口になります。挙動を知っておくと迷いません。アイドルのteammateの行は、パネル全体がアイドルになって30秒後に隠れ、次のターンで戻ります。アイドルが3体を超えると、余りはN idle agentsの1行にまとまり、Enterで展開できます。行が消えても、teammateは停止していません。隠れただけです。選んだteammateはxで止め、Ctrl+Tでタスクリストを切り替えます。

コスト面では、in-processのteammateのリクエストはメイン会話のキャッシュTTLの枠に入りません。保持は既定で5分で、Claudeのサブスクリプションでも同じです。1時間にしたいときは、subagentPromptCacheTtlを1hにします。

split-paneを待たずに済ませる方法もあります。サブエージェントは1セッションの中で完結します。別々に動かしたセッション同士は、クロスセッションメッセージで結果を渡せます。Gitワークツリーを使えば、チーム調整なしで複数のClaude Codeセッションを自分で動かせます。Zellijに手でセッションを並べる人は、この方法でsplit-paneなしに作業を進められます。

Zellij対応のfeature requestは何を求めているか

Issue #31901のタイトルは「Native Zellij support as alternative to tmux for Agent Teams and /terminal-setup」で、ラベルはenhancement area:tui area:agents、状態はopenです。要望は3点あります。

  • Agent Teamsのteammate起動先として、tmuxの代わりにZellijを使えるようにする
  • /terminal-setupの対応端末一覧にZellijを加える
  • ZellijがサポートするKitty keyboard protocolを正しく扱う

提案された実装は、tmuxを$TMUXで検出しているのと同じ要領で$ZELLIJを検出する形です。zellij action new-tab --name <agent>とzellij action write-charsでteammateを起動し、独立したコマンドの実行にはzellij run --を使います。

反応は増え続けています。2026年7月5日のコメントでは👍が53件でしたが、その後も増えています。コメントは3件で、動機はそれぞれ違います。

あゆみ

Issue #31901の動き

  1. 2026-03-07Issueが立つ

    Issue作者は、自作プラグインzellij-workflowを挙げ、Zellijがzellij action系のCLIで操作しやすいことを根拠に提案しています。

  2. 2026-04-01レイアウト面の要望と、シムの紹介

    tmuxを使うある利用者は、select-layoutが正しいチェックサムのレイアウト文字列を要求するため、5〜7体のエージェントを並べる配置を組むのに手間取ると述べています。ZellijならKDL形式のレイアウトファイルで「メイン1カラム+2×3グリッド」を宣言的に書けるという主張です。同日のうちに別の参加者が、tmuxコマンドをzellij actionに翻訳する第三者公開のシムを紹介しています。

  3. 2026-06-22iTerm2が公式対応

    v2.1.186でteammateMode: "iterm2"が入ります。

  4. 2026-07-05Ghosttyユーザーの視点

    Ghosttyはsplit-pane非対応で、tmuxからZellijに乗り換えた人にとっては、Zellij経由がsplit-paneチームに至る唯一の経路だと述べています。約10のリポジトリをまたいでZellijを使う日常のため、in-processへのフォールバックでは機能の主な価値を失うとのことです。

2つのコミュニティ製ツールは役割が違う

Issueに出てくる統合は2つあり、役割が違います。取り違えると期待した結果になりません。

zellij-workflowは、Issue作者が公開している第三者のClaude Codeプラグインです。MITライセンスで、公式の保証はありません。導入は/plugin installで、Issue作者のマーケットプレイスを指定します。できるのはZellijのタブやペインを作ること、タブ名に状態アイコン(準備完了・作業中・入力待ち・圧縮中)を出すことです。アイコンはPreToolUse・PostToolUse・Stopのフックとwasmプラグインで更新されます。コマンドは/run-in-new-tabと/start-issue-in-new-tabで、Agent Teamsのteammateを分割表示する機能ではありません。Zellijで複数のClaude Codeセッションを手で並べる人のための道具です。

split-paneをZellijで出すのは、tmuxコマンドをzellij actionに翻訳するシムのほうです。第三者が公開しているもので、tmux前提の判定を通します。コメント投稿者は、これでsplit-paneが動いたと報告しています。

シムが無理をしている点

7月5日のコメントは、シムの内部を具体的に挙げています。

つまり、tmux向けのコマンドが上流で変わるたびに壊れることがある作りです。同じコメントも「新しいtmuxコマンドが上流に入ると、Zellijユーザー全員のteammateが静かに壊れる」と懸念しています。CIや本番相当のワークフローに組み込む前に、単発のテストタスクで確かめるのが現実的です。

見る点は3つです。ペインがteammateの終了後に閉じるか。teammateが増減しても配置が崩れないか。in-processのときと同じ結果が返るか。

Zellij対応はなぜ止まっているのか

コメントは「実装の大半は回避策を消す作業」と見ています。ただ、これは投稿者側の見立てで、Anthropicからの返信はIssueに付いていません。

よくある質問

Zellijを使っていてもAgent Teamsの機能は同じですか

メッセージの送受信と共有タスクリストの使い方は同じです。違うのは見え方で、ペインが分かれずエージェントパネルで切り替えます。制約は前述のin-processの節のとおりです。

/terminal-setupでZellijのShift+Enterは有効になりますか

/terminal-setupの対象一覧にZellijは含まれません。tmuxの設定はClaude Code tmux設定にあります。Ctrl+Jまたは\とEnterは、どの端末でも設定なしで改行になります。

まとめ

Zellijユーザーの判断材料は2つあります。in-processでは/resumeと/rewindでteammateが戻らないこと。シム経由のsplit-paneは、tmuxコマンドの変更で静かに壊れることがあることです。この2点が許容できるかで、表示方法が決まります。表示モードの設定はteammateMode、動かないときの切り分けはAgent Teamsのトラブルシューティングにあります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →