teammateModeでAgent Teamsの表示方法を切り替える
Agent Teamsのteammateをin-process表示にするかsplit paneにするか。teammateModeの4値の違いと、tmux/iTerm2が必要になる条件を解説します。
このTipsでできること
teammateModeは、Agent Teamsでリードが立てたteammateの表示先を、メインのターミナル内に留めるか、teammateごとに別ペインへ分けるかを切り替えるsettings.jsonのキーです。in-process・auto・tmux・iterm2の4値があり、どれを選ぶかでteammateの並行作業をどこまで一望できるかが変わります。
teammateModeを使う前提 — Agent Teams自体が実験的機能
teammateModeはAgent Teamsのteammate表示方法を切り替えるだけの設定で、Agent Teams機能そのものを有効にするキーではありません。Agent Teamsは既定で無効です。有効にするにはsettings.jsonか環境変数でCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定する必要があります。
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}この変数を設定していないセッションでは、チームがセッション開始時に組成されず、チーム用のディレクトリも作られず、Claudeがteammateを立てたり提案したりすることもありません。teammateModeだけを設定してteammateが1つも立たない場合、まずこの前提を確認します。
Agent Teamsにはセッション再開・タスク調整・シャットダウン挙動まわりに既知の制限があります。本番相当のタスクに使う前に、小さいタスクで一度動きを確認しておくのが実務的です。
teammateModeの4つの値
| 値 | 挙動 | 前提環境 |
|---|---|---|
in-process | 挙動全teammateをメインターミナル内に表示。既定値 | 前提環境どの端末でも動く |
auto | 挙動tmux内で実行中、またはiTerm2かつit2 CLIがPATH上にあればsplit pane、それ以外はin-process | 前提環境tmuxまたはiTerm2+it2(無ければin-processにフォールバック) |
tmux | 挙動split pane表示。ターミナルからtmuxかiTerm2かを自動判定 | 前提環境tmuxまたはiTerm2+it2 |
iterm2 | 挙動iTerm2ネイティブのsplit paneを明示的に使う(バージョン2.1.186以降) | 前提環境iTerm2+it2 CLI必須 |
{
"teammateMode": "auto"
}セッション単位で1回だけ変えたい場合は--teammate-modeフラグで上書きできます。このフラグは実験的な位置づけでclaude --helpには表示されません。
claude --teammate-mode autoin-process表示では、プロンプト入力欄の下にあるエージェントパネルからteammateを選びます。上下矢印キーで選択、Enterでそのteammateのトランスクリプトを開いてメッセージを送信、Escapeで選択中teammateの実行中ターンを中断、という操作系です。split pane表示ではこの操作に加えて、ペインを直接クリックしてteammateとやり取りできます。
split pane表示に必要なもの
auto・tmux・iterm2のいずれも、split pane表示にはtmuxまたはiTerm2(it2 CLI付き)が要ります。どちらも入っていない環境でautoを選んだ場合は、エラーにはならずin-process表示にフォールバックします。一方iterm2を明示指定した場合は、it2 CLIが見つからないとインストールコマンド付きのエラーが表示され、フォールバックはしません。
- tmux: OSのパッケージマネージャーからインストールします
- iTerm2:
it2CLIをインストールし、iTerm2のSettings → General → Magic → Enable Python APIを有効にします
tmuxには一部OSで既知の制限があり、macOS上での動作が最も安定しています。iTerm2からtmuxに入る場合はtmux -CCが推奨の入口です。
デフォルトはいつ変わったか
teammateModeの既定値はバージョン2.1.179でautoからin-processに変わりました。それより前のバージョンでsplit pane表示を使っていたセッションは、明示的に"auto"か"tmux"を設定しない限り、アップグレード後は1つのターミナル内表示に戻ります。
| バージョン | 変更点 |
|---|---|
| 2.1.179より前 | 変更点既定値はauto。tmux/iTerm2があれば自動でsplit pane |
| 2.1.179 | 変更点既定値がin-processに変更 |
| 2.1.186 | 変更点teammateMode: "iterm2"を追加。iTerm2ネイティブsplit paneを明示指定可能に。split pane表示でもリードのエフォートレベルがteammateに伝わるように |
| 2.1.234 | 変更点teammateDefaultModel設定が削除。残存する値はClaude Codeが無視する |
エフォートレベルの継承についてもversion差があります。teammateはリードのエフォートレベルを引き継ぎますが、split pane表示でこれが効くようになったのはバージョン2.1.186からです。それより前のバージョンでは、split pane表示のteammateにリードのセッションエフォートが渡っていませんでした。
teammateのモデルを指定する
teammateが使うモデルは、プロンプトで直接指定するか、CLAUDE_CODE_SUBAGENT_MODEL環境変数で決めます。プロンプトでモデル名を指定しない場合、Claude Codeはリードの現在のモデルでteammateを走らせます(CLAUDE_CODE_SUBAGENT_MODELが設定されていれば、そちらが優先されます)。
Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.指定したモデルは、組織のavailableModels許可リストと照合されます。ブロックされた場合、opusのようなファミリーエイリアスならAnthropic APIとClaude Platform on AWS上では許可リスト内の最新バージョンに差し替わり、それ以外のブロックされた値はリードのモデルにフォールバックします。許可リストの設計自体はClaude Code組織管理ガイドで扱っています。
teammateに計画承認を求める
複雑な作業やリスクのある変更では、teammateに実装前の計画承認を求められます。指示に「実装前に計画を承認して」のような条件を含めると、teammateは読み取り専用のplanモードで計画を作り、リードに承認を求めます。
Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.リードは自律的に計画を承認・却下します。却下された場合、teammateはplanモードのままフィードバックを反映して再提出し、承認されて初めて実装に入ります。承認基準を絞りたいときは「テストを含む計画だけ承認して」「データベーススキーマを変更する計画は却下して」のようにプロンプト側で条件を渡します。teammateModeの値そのものはこの承認フローの有無に影響しません。in-process表示でもsplit pane表示でも同じ仕組みが働きます。
Agent Teamsとサブエージェントは何が違うか
Agent Teamsとサブエージェントはどちらも作業を並列化する仕組みですが、ワーカー同士が直接やり取りできるかどうかが根本的に違います。
| 観点 | サブエージェント | Agent Teams |
|---|---|---|
| 起動元 | サブエージェントメインエージェントがTaskツールで起動 | Agent Teamsリードがteammateとして起動 |
| ワーカー間通信 | サブエージェントできない(結果はメインにのみ返る) | Agent Teamsできる(共有タスクリストで直接連携) |
| 向くタスク | サブエージェント逐次的な作業・同一ファイル編集・依存の多い工程 | Agent Teams並列探索・競合仮説の検証・フロントエンド/バックエンド/テストの分担 |
| 調整コスト | サブエージェント相対的に小さい | Agent Teamsチーム間の同期が乗る分、相対的に大きい |
| 表示制御キー | サブエージェントなし(エージェントパネルに表示されるのみ) | Agent TeamsteammateMode |
エージェントパネルにはサブエージェントとteammateが同じ場所に並ぶため、パネルを見ただけではAgent Teamsが編成されたのか通常のサブエージェント呼び出しなのかを区別できません。Claudeがteammateの代わりにサブエージェントを選ぶこともあるため、確実にチームを組みたいときは「agent teamを使って並列で調査して」のように明示的に依頼します。逐次的なタスクや依存関係の多い作業では、Agent Teamsの調整コストがかえって足かせになるため、単一セッションかサブエージェントの方が向きます。
よくあるつまずき
teammateDefaultModelという設定名で検索して見つかることがありますが、これはバージョン2.1.234で削除された設定キーです。settings.jsonに残っていてもClaude Codeは値を無視します。teammateのモデルを固定したい場合は、プロンプトで指定するかCLAUDE_CODE_SUBAGENT_MODEL環境変数を使う必要があります。
もう1つの典型的なつまずきは、teammateModeを"auto"や"tmux"に設定したのにin-process表示のままというケースです。多くの場合、tmuxが起動していない、またはiTerm2でit2 CLIがPATH上にないことが原因です。autoは前提が揃わなければ黙ってin-processにフォールバックするため、エラーメッセージが出ません。split pane表示を確実に使いたい場合は"iterm2"を明示指定すると、it2が無いときにインストール手順付きのエラーで気づけます。
エージェントパネルの表示にもversion差があります。バージョン2.1.199以降は、他のteammateやサブエージェントが作業中である限り、アイドルになったteammateの行がパネルに残り続け、全員がアイドルになってから30秒後に非表示になります(非表示中もteammateは動作・応答可能です)。バージョン2.1.181から2.1.198の間は、他のteammateが作業中でも自分のターンが終わってから30秒でアイドル行が個別に消えていました。2.1.181より前のバージョンではアイドル行は非表示になりません。4人以上のteammateが同時にアイドルになると、4人目以降の行は「2 idle agents」のように1行へ折りたたまれ、選択してEnterで展開できます。
よくある質問
teammateModeを設定しなかった場合、実際どちらの表示になりますか
バージョン2.1.179以降はin-process(メインターミナル内表示)が既定値です。それより前のバージョンではautoが既定値でした。
auto・tmux・iterm2はどう使い分ければいいですか
tmuxとiTerm2のどちらでも動けばよいならautoが手間なく動きます。tmux環境で確実にsplit paneを使いたい・iTerm2でも自動判定に任せたいならtmux、iTerm2のネイティブsplit paneを明示的に使いたい・it2が入っていないときにエラーで気づきたいならiterm2を選びます。
teammateごとに違うモデルを割り当てられますか
できます。「4人のteammateを立てて、それぞれ別のモジュールを担当させてください。1人目はOpus、残りはSonnetで」のようにプロンプトでteammateごとにモデルを指定します。モデル名を省略したteammateは、CLAUDE_CODE_SUBAGENT_MODELが未設定ならリードの現在のモデルを引き継ぎます。teammateModeはあくまで表示方法の設定なので、モデル割り当てには関与しません。
サブエージェント(subagents)とteammateは同じ設定で表示が変わりますか
サブエージェントもteammateと同じエージェントパネルに表示されるため、パネルを見ただけではチームが編成されたのか区別できません。ただしteammateModeが制御するのはAgent Teamsのteammate表示であり、通常のサブエージェント呼び出しの挙動そのものを変えるキーではありません。
まとめ
teammateModeはAgent Teamsのteammateをin-process表示にするかsplit pane表示にするかを決め、既定値はバージョン2.1.179でautoからin-processに変わりました。split pane表示にはtmuxかiTerm2(it2 CLI付き)が必要で、揃っていない環境でautoを指定すると気づかないままin-processにフォールバックします。teammateのモデル指定はteammateModeとは別の仕組みで、削除済みのteammateDefaultModelではなくプロンプトかCLAUDE_CODE_SUBAGENT_MODEL環境変数で行います。