--teammate-mode（チームメイトモード）

Claude Code の Agent Teams を使いたいけど tmux も iTerm2 も無い環境で動かしたい人向け

Claude Code には Agent Teams という、複数のチームメイトAIを同時に動かす実験段階の機能があります。--teammate-mode は、そのチームメイトを「どう画面に並べるか」を1回限りで切り替える起動時の追加指定です。具体的には「同じ画面の中で順番に切り替えて見る」か「画面を分割してそれぞれの担当に専用の小窓を割り当てる」かの2択。

分割表示は tmux か iTerm2 が必要で、~/.claude/settings.json に "teammateMode": "tmux" を書いている場合は VS Code の内蔵ターミナルや Windows Terminal では起動エラーになります。私もその設定が残ったまま VS Code に切り替えて詰まりました。そこで claude --teammate-mode in-process を付けて起動し直して、同じ画面の中で Shift+Down キーを押して順番にチームメイトを覗く形に逃がします。

噛み砕くと

例えるなら、3人の助っ人を呼んでチームで仕事を頼むときの「席の配置」の指定です。会議室を4分割して各人にホワイトボードを1枚ずつ渡すか（split panes、つまり分割表示）、それとも1枚のホワイトボードを順番に使い回すか（in-process、つまり1画面内で切替）。

分割表示の方が3人の作業を同時に眺められて便利だけど、その「会議室を分割できる仕組み」自体は手元の環境にないと使えません。多目的ルームみたいな専用の備品が要る。手元にその備品が無いなら、1枚のホワイトボードを順番に切り替える方式の方が確実に動く、というだけの話です。

大事な前提：Agent Teams 自体が実験段階でデフォルト無効

--teammate-mode を渡す前に、そもそも Agent Teams 機能を有効化する必要があります。これを忘れて --teammate-mode in-process だけ渡しても、チームメイト機能自体が動かないので何も起きません。私が最初にハマった落とし穴です。

有効化は CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 をターミナル起動時の覚え書きに登録するか、~/.claude/settings.json の env セクションに書き込みます。さらに Claude Code 本体が v2.1.32 以降である必要があります。古いままだとこの追加指定自体が認識されません。

「会社の Mac で固定した tmux 設定が、出先の VS Code で牙を剥く」シーンで実演

具体的に動かすイメージで追います。題材は「会社の Mac では iTerm2 + tmux 構成で settings.json に "teammateMode": "tmux" を書いて固定していた人が、出先の個人 PC の VS Code 内蔵ターミナルで同じ claude を起動してハマる」です。レビュアー3人のチームでPRを見てもらう想定で進めます。

ステップ1: Claude Code のバージョンを確認する

まず手元の Claude Code が v2.1.32 以降か確認します。ターミナルで次の1行を打ちます。

$ claude --version

v2.1.32 より古い番号なら、先にアップデート。Agent Teams 対応バージョンに上げないと、ここから先は何をやっても動きません。

ステップ2: Agent Teams 機能をオンにする

ターミナルで次の1行を打って、その画面の中だけでオンにします。

$ export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

毎回打つのが面倒なら、~/.claude/settings.json の env 欄に書き込んで永続化する方が楽です。私は settings.json 派です。

ステップ3: 会社で固定した "teammateMode": "tmux" がそのまま残っている

会社の Mac で Agent Teams を使い始めたときに、毎回 --teammate-mode を付けるのが面倒で settings.json に分割表示モードを固定していたとします。

{
  "teammateMode": "tmux"
}

会社では iTerm2 + tmux 環境なのでこれで快適に動いていました。出先で個人 PC の VS Code を開いた今も、この設定はそのまま残っています。本人はそれを意識していません。

ステップ4: VS Code 内蔵ターミナルで claude を起動して、初心者がやりがちな勘違いに当たる

$ claude

立ち上げた瞬間、起動エラー。「PR を3人のレビュアーで見て」と頼む前の段階で詰まります。エラーメッセージを見て「VS Code 内蔵ターミナルだから auto モードが分割表示を選んでしまったんだろう」と思いがちですが、ここに勘違いがあります。

実は auto モードは、tmux のセッションの中で claude を起動しているときだけ分割表示を選びます。VS Code の内蔵ターミナルは tmux セッションではないので、本来 auto は最初から「1画面の中で切り替える」方式（in-process）を選んでくれます。

問題が起きるのは ~/.claude/settings.json に "teammateMode": "tmux" を明示的に書いていた場合です。会社の Mac で iTerm2 + tmux 構成のときに設定しておいたものが、別の PC の VS Code 内蔵ターミナルでも残っていて、分割表示を試みて起動エラーになります。

この場合の解決策が --teammate-mode in-process です。設定を書き換えずに、このセッションだけ in-process に強制できます。

ステップ5: --teammate-mode in-process を付けて起動し直す

一度 Claude Code を抜けてターミナルに戻り、追加指定を足して起動し直します。

$ claude --teammate-mode in-process

settings.json の "tmux" 指定は無視されて、このセッションだけ in-process で立ち上がります。「PR #142 を3人のレビュアーで見て」と頼むと、画面を分割せず、同じ1つの対話画面の中で3人のチームメイトが順番に走ります。

ステップ6: Shift+Down でチームメイトを切り替えて見る

in-process モードでは、Shift+Down キーを押すと「レビュアー1 → レビュアー2 → レビュアー3 → 自分」の順で画面が切り替わります。今アクティブなチームメイトに直接メッセージを打って指示を出せます。「セキュリティ観点でもう1往復」とか「テストカバレッジ気になる箇所だけ抜き出して」みたいに、個別に追加注文できる感じです。

つまり --teammate-mode は何をしてくれるのか

• やってくれる: Agent Teams のチームメイトの「画面の見せ方」を、そのセッション1回限りで切り替える。auto・in-process・tmux の3択から選べて、起動時に渡した値が settings.json の teammateMode より優先される
• やってくれない: Agent Teams 機能自体の有効化はしてくれない。チームメイトを何人にするかも決めてくれない。それらは別の場所で指定する
• 意味が薄い場面: 普段から tmux セッションの中で claude を起動している人。auto モードが勝手に分割表示を選んでくれるので、この追加指定を足す意味がほぼ無い

使いどころ3シナリオ

シナリオ1: settings.json に "tmux" 固定を入れたまま VS Code に切り替えるとき

会社の Mac で iTerm2 + tmux 環境のときに settings.json へ "teammateMode": "tmux" を書いて固定していた人が、出先で VS Code 内蔵ターミナルに切り替えるとここで詰まります。auto モードに戻せば VS Code でも自動で in-process を選んでくれますが、設定を毎回書き換えたくない場合は claude --teammate-mode in-process を渡して、このセッションだけ強制的に1画面切替に逃がせます。VS Code の tasks.json に claude --teammate-mode in-process を登録しておくと、出先で起動する用のショートカット代わりになります。

シナリオ2: SSH接続先のサーバで一時的にチームを立てたいとき

SSH でつないだ先のサーバに tmux が入っていない、入れる権限も無い場面では --teammate-mode in-process 一択です。私はクライアントの本番サーバに一時調査で入るときがあって、自由にプログラムを入れられないので、in-process で1画面の中だけで完結させます。Shift+Down で切り替えれば、3人のチームメイトの出力を順番に確認できます。

シナリオ3: 普段のターミナルから無理やり分割表示を呼びたいとき

普段は tmux を使わない人が、Agent Teams のときだけ分割表示で使いたい場合は claude --teammate-mode tmux を渡します。手元に tmux か iTerm2 のどちらかが入っていれば、Claude Code が自動でそれを呼び出して分割表示を立ち上げます。「普段使うターミナルアプリは iTerm2 だけど、tmux は触ったことがない」みたいな人でも、この一行で分割表示にできます。iTerm2 側で it2 という付属の小道具コマンドを使えるようにしておく必要があります。

初心者が踏みやすい落とし穴

• Agent Teams 自体を有効化してない。CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 を先に設定しないと、--teammate-mode を渡してもチームメイト機能自体が動かない。私の初回ハマりポイント
• VS Code 内蔵ターミナル・Windows Terminal・Ghostty で分割表示は動かない。公式が明示している3つの非対応環境。settings.json に "teammateMode": "tmux" を指定した状態で起動するとエラーになる。auto に任せれば VS Code でも自動で in-process を選んでくれる。確実に固定したいなら settings.json で "teammateMode": "in-process" を恒久指定する
• auto の判定基準を勘違いする。「tmux がパソコンに入っていれば auto は分割表示を選ぶ」と思いがちだけど、実際は「tmux のセッションの中で claude を起動しているか」で判定される。tmux new -s work の中で claude を叩いた場合は分割表示、普段のターミナルでそのまま claude を叩いた場合は1画面切替
• settings.json の teammateMode と起動時指定の優先関係を忘れる。両方ある時は起動時に渡した方が勝つ。settings.json で永続的に "tmux" にしていても、claude --teammate-mode in-process を渡せばそのセッションだけは1画面切替になる
• Claude Code 本体のバージョンが古い。v2.1.32 より前は Agent Teams 自体が無いので、--teammate-mode も認識されない。claude --version で先に確認
• iTerm2 で分割表示を使うのに it2 小道具を入れていない。iTerm2 単体では足りなくて、付属の it2 コマンドを使えるようにする一手間が要る。これを忘れると --teammate-mode tmux を渡しても iTerm2 側で分割表示が立ち上がらない
• 「--teammate-mode tmux という名前だから tmux を立ち上げてくれる」と思う。実際は「分割表示モード」の意味で、tmux セッションの中にいるか iTerm2 が手元にあるかを auto-detect するだけ。tmux が裏で動いていない場所で渡しても、tmux を新しく起動してはくれない。tmux が無くて iTerm2 だけある Mac でも、この一行で分割表示が立ち上がる

書き方

claude --teammate-mode <auto|in-process|tmux>

やってみるとこうなる

入力

claude --teammate-mode in-process

出力例

Claude Code がチームメイトを画面分割せず、同じ1つの対話画面の中で順番に走らせる形で起動する。Shift+Down キーでチームメイトを切り替えて、それぞれにメッセージを送れる状態になる。tmux も iTerm2 も無い場所でも動く。

関連項目

• /agent-teams（準備中）
• settings.json（セッティングス・ジェイソン）
• /subagent-types（準備中）
• claude agents（クロード・エージェンツ）
• --tmux（ティーマックス）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference