Claude Media
teammateModeでAgent Teamsの表示方法を切り替える
Claude CodeTips

teammateModeでAgent Teamsの表示方法を切り替える

Agent Teamsのteammateをin-process表示にするかsplit paneにするか。teammateModeの4値の違いと、tmux/iTerm2が必要になる条件を解説します。

読了目安 約9分

このTipsでできること

teammateModeは、Agent Teamsでリードが立てたteammateの表示先を切り替えるsettings.jsonのキーです。メインのターミナル内に留めるか、teammateごとに別ペインへ分けるかを選びます。in-process・auto・tmux・iterm2の4値があり、既定値はin-processです。

teammateが立たない・勝手に立つときの前提

teammateModeは表示方法を切り替えるだけで、Agent Teams機能そのものを有効にするキーではありません。Agent Teamsは既定で無効で、settings.jsonか環境変数でCLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1を設定して初めて動きます。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

この変数が無いセッションでは、teammateModeを設定してもteammateは1つも立ちません。逆に有効にすると、Claudeが名前を付けて呼んだサブエージェントはteammateとして起動します。チームを頼んでいない委任でも、teammateが立つことがあります。

サブエージェントとして動かしたいだけなら、同じ変数を0にします。非対話モード(-p)やAgent SDKのセッションではteammateは立たず、名前付きのサブエージェントも通常のサブエージェントとして走ります。

Agent Teamsにはセッション再開・タスク調整・シャットダウンまわりの既知の制限があります。/resumeと/rewindはin-processのteammateを復元しないので、再開後はリードに新しいteammateを立て直させます。

4つの値と、操作の違い

値挙動前提環境
in-process挙動全teammateをメインターミナル内に表示。既定値前提環境どの端末でも動く
auto挙動tmux内で実行中、またはiTerm2ならsplit pane。それ以外はin-process前提環境tmux、またはiTerm2
tmux挙動split pane表示。ターミナルからtmuxかiTerm2かを自動判定前提環境tmuxまたはiTerm2+it2
iterm2挙動iTerm2ネイティブのsplit paneを明示指定(2.1.186以降)前提環境iTerm2+it2 CLI必須

autoの条件は、公式ページ同士で書き方が違います。Agent Teamsのページは「iTerm2でit2 CLIが入っているとき」、settingsリファレンスは「iTerm2でit2がPATHにあるか、tmuxが入っているとき」です。iTerm2でtmuxだけを入れている環境では、2つの記述が分かれます。迷う環境では、挙動が明確なtmuxかiterm2を指定する選択肢があります。

セッション単位で1回だけ変えたいときは--teammate-modeで上書きできます。

claude --teammate-mode auto

このフラグは実験的な扱いで、claude --helpの出力には載りません。v2.1.287でもteammateを含む行はありません。一方でCLIリファレンスにはin-process(既定)・auto・tmux・iterm2の4値を取るフラグとして載っています。

くらべる

in-processとsplit paneの操作

既定

in-process

プロンプト入力欄の下のエージェントパネルで、上下矢印キーでteammateを選び、Enterでそのteammateの画面を開いてメッセージを送ります。選択中のteammateはxで停止でき、Ctrl+Tでタスクリストの表示を切り替えます。teammateの画面を開いている間のEscapeは、そのteammateの実行中のターンを中断します。

tmux / iTerm2

split pane

teammateごとに別ペインが開き、全員の出力が同時に見えます。ペインを直接クリックすれば、そのteammateとやり取りできます。

in-processのteammateを開いている間は、/modelと/fastが実行されません。この2つはリードの設定を変えるコマンドで、teammate自身には効かないためです。/compact・/clear・/rewindはリードの会話に作用するので、実行前に確認が入ります。

split paneにならないときの切り分け

"auto"や"tmux"を設定したのにin-processのままなら、次の順に見ていきます。

手順

split paneにならないとき

  1. 1

    tmuxの中でClaude Codeを起動しているか

    autoは、tmuxの中で動いているときにsplit paneを使います。tmuxの外で起動していて、iTerm2でもなければ、in-processへ戻ります。

  2. 2

    tmuxがPATHにあるか

    which tmux

    出力が空なら、OSのパッケージマネージャーでtmuxを入れます。

  3. 3

    iTerm2なら it2 CLI と Python API

    it2 CLIを入れ、iTerm2のSettings → General → Magic → Enable Python APIを有効にします。iTerm2からtmuxに入るときはtmux -CCが推奨の入口です。

  4. 4

    iterm2を明示指定してエラーで確かめる

    "iterm2"にすると、it2が無いときにインストールコマンド付きのエラーが出ます。autoも、2.1.186以降はit2が見つからないと警告を出します。iTerm2でtmuxも使える環境では、autoとtmuxでit2の導入かtmuxへの切り替えを促す画面が出ます。

そもそもsplit paneに対応していない端末もあります。VS Codeの統合ターミナル、Windows Terminal、Ghosttyでは使えません。Zellijも前提の端末に含まれていません。tmuxは一部のOSで既知の制限があり、従来はmacOSで最も安定して動くとされています。

tmuxセッションがClaude Codeの終了後も残ることがあります。tmux lsで一覧を出し、チームが作ったセッションをtmux kill-session -t <セッション名>で終了します。

バージョンごとの違い

バージョン変更点
2.1.178変更点TeamCreateとTeamDeleteツールが削除。環境変数を有効にすると、セッションごとに暗黙のチームが1つ作られ、Agentツールのnameパラメーターでteammateを直接立てる
2.1.186変更点teammateMode: "iterm2"を追加。split pane表示でもリードのエフォートレベルがteammateに伝わる
2.1.199変更点他のteammateやサブエージェントが作業中の間、アイドルのteammateの行がパネルに残る
2.1.234変更点設定画面の「Default teammate model」とteammateDefaultModelが削除。残った値は無視される

エージェントパネルのアイドル行は、バージョンで消え方が違います。2.1.199以降は、パネル内の全員がアイドルになってから30秒後に行が隠れ、次のターンで戻ります。隠れてもteammateは動作・応答できます。2.1.181〜2.1.198は、他のteammateが作業中でも、自分のターンが終わって30秒で個別に消えました。2.1.181より前は隠れません。

行が消えたteammateには、名前を指定してメッセージを送ると行が戻ります。アイドルのteammateが4人以上になると、4人目以降は「2 idle agents」のような1行に畳まれ、選択してEnterで展開できます。

teammateのモデルの決まり方

モデルはteammateごとに、次の順で最初に当てはまるものが採用されます。

  1. 立てるときのプロンプトでそのteammateに指定したモデル
  2. サブエージェント定義から立てた場合は、定義のmodel(inheritならリードのモデル)
  3. inherit以外に設定されたCLAUDE_CODE_SUBAGENT_MODEL
  4. リードの現在のモデル

2.1.251より前は、CLAUDE_CODE_SUBAGENT_MODELが最優先でした。CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1(2.1.257以降)を設定すると、1と2は効かなくなります。

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

立てたあとのモデルは固定です。リードが/modelで切り替えても、動いているteammateには届きません。エフォートレベルは別で、teammateはリードの設定に追従します。

選んだモデルは組織のavailableModels許可リストと照合されます。ブロックされると、opusのようなファミリーエイリアスはAnthropic APIとClaude Platform on AWSで許可リスト内の最新版に差し替わります。それ以外はリードのモデルへ戻ります。許可リストの設計はClaude Code組織管理ガイドにあります。

表示方法で変わるキャッシュと定義の扱い

in-processのteammateのリクエストは、メイン会話のキャッシュTTLの区分に入りません。キャッシュの保持は既定で5分で、Claudeのサブスクリプションでも同じです。1時間に延ばすには、subagentPromptCacheTtlを1hにします。1時間のキャッシュ書き込みは、APIで高い料率で課金されます。

サブエージェント定義から立てたteammateでは、表示方法で定義の使われ方が変わります。in-processでは、定義の本文が既定のシステムプロンプトに追記されます。split paneでは、本文が既定のシステムプロンプトの代わりに使われます。

定義のmcpServersは、split paneのteammateにだけ適用されます。in-processのteammateはこのフィールドを無視します。skillsはどちらの表示方法でも適用されません。

リードを--setting-sourcesで起動すると、teammateも同じ制限つきの設定ソースから読み込みます。v2.1.281より前は、split paneのteammateがすべての設定ソースを読み込んでいました。

実装前の計画を作らせる

複雑な変更では、teammateに先に計画を作らせられます。リードをplanモードにしてからteammateを頼むと、そのteammateは計画ができるまで読み取り専用のplanモードで動きます。

Spawn an architect teammate to refactor the authentication module.

計画ができるとリードに承認依頼が届き、Claude Codeがリードのセッション内で即座に承認します。リード(Claude)が計画の中身を読んで却下する仕組みではありません。承認後にteammateはplanモードを抜けて実装に入りますが、編集やコマンドは通常どおり許可プロンプトを通ります。teammateの許可プロンプトはリードのセッションに出るので、そこで自分で答えます。

Agent Teamsとサブエージェントの違い

どちらも作業を並列化しますが、ワーカー同士のやり取りと調整の持ち方が違います。

観点サブエージェントAgent Teams
コンテキストサブエージェント独立。結果は呼び出し元に返るAgent Teams独立。完全に自律
連絡サブエージェント結果を返す。名前付きで起動したものは相互にメッセージも送れるAgent Teamsteammate同士が直接メッセージを送る
調整サブエージェントメインエージェントが全体を管理Agent Teamsメッセージのやり取りと、Taskツールを持つエージェント向けの共有タスクリスト
トークンコストサブエージェント低い。結果が要約されて戻るAgent Teams高い。teammateごとに別のClaudeインスタンス
表示制御キーサブエージェントなしAgent TeamsteammateMode

逐次的な作業、同じファイルへの編集、依存の多い工程では、調整の負荷が効いて単一セッションやサブエージェントのほうが向きます。並列調査、競合仮説の検証、フロントエンド・バックエンド・テストの分担のように、独立して進められる仕事で効きます。サブエージェント側の詳細はサブエージェントの使い方にあります。Claude Codeの全体像から見ると、Agent Teamsは並列化の選択肢の1つです。

サブエージェントがメッセージを送るには、ツールにSendMessageが要ります。v2.1.206以降は、ほかの名前付きエージェントの一覧も渡されます。

エージェントパネルにはサブエージェントとteammateが同じ場所に並ぶので、見た目だけでは区別できません。確実にチームを組みたいときは「agent teamを使って並列で調査して」のように頼みます。

teammateDefaultModelで検索してきた人へ

teammateDefaultModelはバージョン2.1.234で削除された設定キーです。settings.jsonに残っていてもClaude Codeは値を無視します。teammateのモデルを固定するには、立てるプロンプトで名前を指定するか、CLAUDE_CODE_SUBAGENT_MODELを使います。

まとめ

split paneで確実に表示したいときは、前提が欠けたらエラーで気づけるiterm2かtmuxを明示する選択肢があります。

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

関連する記事

Claude Code をもっと見る →