🤝

10分で動く：MacでClaude Code Agent Teams（チーム機能）をtmuxで使う手順（非エンジニア向け）

に公開
macOS
terminal
tmux
Cursor
Claude Code
tech

デザイナー/PMなど「Terminalは触るけど、専門用語はよく分からない」みたいな非エンジニア向けに、Claude Code の チーム機能（Agent Teams） を使い始めるまでを、迷子になりにくい形でまとめました。

この記事はAIと一緒に書き、人間が調整しています。

この記事でできるようになること（読み終わったら）

  • Agent Teams（セッションのチーム）を使えるようになる
  • tmux(画面分割)の中で claude を起動できる
  • よくある迷子（「どこのディレクトリに作った？」など）を回避できる

この記事は「まず動かす」を最優先にしています。細かい仕組みや高度な設定（teammateMode 固定など）は、必要になったら後でOKです。

基礎知識：
チーム機能（Agent Teams）って何？

Claude（AI）を「複数人チーム」にして並行作業させる機能です。
チーム機能実行中の実際の画面

  • 1人ずつ考えるより速い: たとえば「調べる人」「手順を書く人」「抜け漏れチェックする人」みたいに分担できます
  • 見落としを減らせる: チェック役が最後に確認してくれるので、手順の抜けや危険操作に気づきやすいです
  • やり取りはいつも通り: 人(あなた)は最後に統合された回答（結論）を受け取り、必要なら追加指示できます

この手順では、チームの出力を見やすくするために tmux（Terminal分割ツール） も使います（必須ではないが見やすいのでおすすめ）。

0. 結論（何をすれば動くの？）

やること一覧

やることは大きく3つです。

  1. チーム機能のスイッチをONにする（環境変数を1行追加）
  2. （任意）画面を分割する道具を入れる（tmux）
  3. 作業フォルダに移動して、tmuxの中で claude を起動する

前提

本記事の前提となる作業環境は以下です。

  • OS: macOS
  • 作業フォルダ例: ~/Documents/agent-team-demo（Finderだと「書類」相当）

1. 準備：必要なもの

この手順で使うもの:

  • Terminal（macOS標準の「ターミナル」アプリでOK）
  • Claude Code（claude コマンドが使える状態）
  • （任意）Homebrew（アプリを入れるための道具。tmuxインストールで使う）

「Claude Codeが入ってるか」だけ先に確認するなら、Terminalでこれを実行します:

claude --version

成功の目印: 2.x.x (Claude Code) みたいな表示が出ればOKです。

2. チーム機能をONにする（.zshrcに1行追加）

2-1. 何をしているの？

「チーム機能をONにするためのスイッチ」を、Terminal起動時の設定メモ（.zshrc）に書き足します。

補足: この手順は macOSの標準設定（zsh） を想定しています。

2-2. コピペで実行（2行）

Terminalでこの2行をそのまま貼って実行します。

echo 'export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1' >> ~/.zshrc
source ~/.zshrc

2-3. ONになったか確認（1行）

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

成功の目印: 1 が出ればOKです。

もし空っぽなら：別のTerminalを開き直して、もう一度 echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS を試してください。

3. （任意）画面を分割する道具「tmux」を入れる

3-1. tmuxって何？

一言でいうと、1つのTerminal画面を“分割”して使えるようにする道具です。
Claude Code のチームを動かすとき、複数人の動きを同時に見やすくなります。

検索でよく出てくる言葉: split panes（画面分割） / in-process（同じ画面内で切り替え表示）

3-2. インストール（コピペ）

brew install tmux
tmux -V

成功の目印: tmux 3.x のような表示が出ればOKです。

もし brew: command not found と出たら：Homebrewが未インストールです。ここだけエンジニアに頼むのが早いです（または公式のHomebrew手順に沿ってインストール）。

4. 作業フォルダに移動する

僕はここで迷子になりました。結構注意かも。

4-1. よくある混乱：「書類」フォルダってどこ？

Finderでは「書類」と見えていても、Terminal上では多くの場合 ~/Documents です。

今回の例だと、作業フォルダはこうです:

  • ~/Documents/agent-team-demo

4-2. まだフォルダを作っていない場合（どっちかでOK）

非エンジニアの方は、まだ agent-team-demo フォルダ自体が無いことがあります。

  • 方法A（Finder）: Finderで「書類（Documents）」の中に agent-team-demo フォルダを作ってください
  • 方法B（Terminal）: これをコピペ（途中のフォルダもまとめて作れます）
mkdir -p "$HOME/Documents/agent-team-demo"

4-3. まず移動してみる（コピペ）

cd "$HOME/Documents/agent-team-demo"

成功の目印: 何も表示されず、次のプロンプトが出ればOKです（エラーが出なければOK）。

4-4. もし「どこに作ったか分からない」場合（検索コマンド）

フォルダ名から場所を探すには、これを実行します。

mdfind "kMDItemFSName == 'agent-team-demo'"

成功の目印: .../Documents/agent-team-demo みたいな「場所（パス）」が表示されます。出てきた場所をそのまま cd します:

cd "/Users/あなたのユーザー名/.../agent-team-demo"

重要: mdfind の結果（パス）は、コピーして 必ず cd "ここに貼る" の形で使ってください（ダブルクォート付き）。
パスにスペースや日本語が入っている場合に、ダブルクォート無しだと失敗しやすいです。

ここまでの作業状態

5. tmuxを起動して、Claude Codeを動かす（コピペ）

5-1. tmuxセッションを作る

tmux new -s agent-demo

成功の目印: 画面が切り替わって、下の方に横長のバー（tmuxのステータス）が出ます。

もし「もう同じ名前がある」と言われたら、代わりにこれで入れます:

tmux a -t agent-demo

5-2. tmuxの中で claude を起動

claude

ここまでで、チーム機能が使える状態になります。

6. Claudeに「チームを作って」と頼む

このテンプレを、そのままClaudeに貼ってOKです。

テンプレA：まずは“動作確認”（最短）

最初はこれがおすすめです。
「何について？」が入っているので、Claudeが追加質問せずに進みやすいです。

Agent Teams でチームを作ってください。
目的は「このmacOS環境で、tmuxの中でclaudeを起動してAgent Teamsが動く」ことの動作確認です。

役割は3つです：

  • 調査役：前提条件（必要コマンド/確認方法）を整理する
  • 手順役：コピペで実行できる手順を作る（成功の目印つき）
  • チェック役：つまずきポイント（例：書類=Documents、tmuxセッション衝突など）をチェックして追記する

作業フォルダは ~/Documents/agent-team-demo です。
最後に「この手順どおりにやればOK」という1つの手順に統合してください。

テンプレB：まずはシンプル（3人・最小）

Agent Teams でチームを作ってください。
役割は3つです：

  • 調査役：まず状況を整理して、必要な情報を集める
  • 手順役：具体的な操作手順を作る（コピペできる形）
  • チェック役：抜け漏れや危険な操作がないか確認する
    それぞれ並列で進めて、最後に1つにまとめてください。

テンプレC：あなたの業務用に置き換える（テンプレ）

動作確認の次は、このテンプレを使うと「実務に持ち込むハードル」が下がります。
（ここを埋める） の部分だけ置き換えて、そのまま貼ってください。

Agent Teams でチームを作ってください。
対象タスクは「（ここを埋める：例：新しいプロジェクトのセットアップ手順を作りたい）」です。
成果物は「コピペ手順」「チェックリスト」「つまずきFAQ」です。
前提は「macOS / Terminal / （必要ならtmux）」です。

役割は3つです：

  • 調査役：必要情報と前提の整理（足りない情報があれば質問する）
  • 手順役：具体手順（成功の目印つき）
  • チェック役：抜け漏れ・リスク確認

最後に、成果物を1つに統合してください。

補足テク：作業場所（フォルダ）を伝える（迷子防止）

Claude は、あなたのTerminalの「今いるフォルダ」を把握する能力を持っていますが、明示的に伝えると認識違いが防げます。
ファイルを探す/手順を作る系の依頼では、最初にこれを1行足すだけで、やり取りが減ります。

いまTerminalの作業場所は ~/Documents/agent-team-demo です。

例えばテンプレAやCの冒頭に、この1行を足してから依頼するとスムーズにいくことがあります。

やってみよう

準備できたら、
動かしてみましょう。

もう動かしてみましたか？まだであれば、上記のコピペで動きます。

  1. この記事の テンプレA を Claude に貼る
  2. 出てきた役割（調査役/手順役/チェック役）を、あなたの仕事に合わせて名前だけ変える
  3. 次からは補足テクを使って迷子を防ぐ

まずは動かして体験してみることが重要です。とにかく動かしてみましょう。もし失敗したら本記事に戻ってきてやり直せばOKです。

実践

上記をやってみると、このように、どう作業するか聞かれると思います。好みにあわせて選択すればよいですが、テンプレAは実験なので、"Yes, and always allow access to agent-team-demo/ from this project" を選択します。↓

進むと、たびたび"Do you want to proceed?(XXをやっていいですか?）"などと聞かれるので、よく読んでYesと回答していきます。

入力・送信してtmuxで画面分割された状態

画面分割された時、選択肢を選べない（入力が効かない）場合

tmuxで画面分割されると、エージェントが質問してきたペインと違うペインにフォーカスが移ることがあります。つまり 「質問が出ているペイン」と「いま入力しているペイン」が違う状態です。

こういう時は、まず、質問（選択肢）が表示されているペインにフォーカスを戻さなければなりません。

手順（キーボードで移動）

  1. Ctrl + b を押す（同時押しではなく、押してから離す）
  2. 次のどれかで、質問が出ているペインへ移動
    • ← / → / ↑ / ↓（矢印）
    • o（次のペインへ移動）
  3. 質問が出ているペインで 1 → Enter（例：Yes）

どのペインが質問のペインか分からない場合

  • Ctrl + b → q を押すと、ペイン番号が一瞬表示されます（それを見ながら移動）

マウスでクリックして切り替えたい場合（任意）

  • Ctrl + b → :（コロン） → set -g mouse on → Enter
    これでペインをクリックしてフォーカス移動できます。

作業中の様子

作業中の様子(後半)

作業完了すると、自動でチームを解散して完了してくれます。↓

完了報告とチームのクリーンアップされた状態

FAQ

tmuxは必須ですか？

必須ではありません。
ただ、複数人の動きを同時に見たいなら tmux が便利です（画面分割できるので）。

teammateMode は設定しないといけませんか？

基本は不要です。まずは tmux の中で claude を起動してみてください。
それでも表示が意図通りにならない時だけ、公式ドキュメントの teammateMode 設定を見ればOKです。

Finderの「書類」フォルダと、Terminalの Documents は同じですか？

多くの場合は同じです。
Finderで「書類」に見えている場所は、Terminalでは ~/Documents になっていることが多いです。

cd がどうしても通りません

まずは場所を探します。

mdfind "kMDItemFSName == 'agent-team-demo'"

出てきたパスを、そのまま cd "..." してください（ダブルクォート重要）。

tmuxを「閉じずに」一旦戻るには？（デタッチ）

  • キー操作: Ctrl + b を押してから、d

成功の目印: もとのTerminal画面に戻ります（tmuxは裏で動き続けます）。

tmuxに戻るには？（アタッチ）

tmux a -t agent-demo

tmuxを終えるには？

tmux内で以下を実行します。

exit

tmuxが起動したか不安です

画面下に横長のバー（tmuxのステータス）が出ていれば、tmuxの中です。

tmuxのセッション名が衝突します（同名があると言われる）

既にあるセッションに入ればOKです。

tmux a -t agent-demo

画面が分割されません（Agent Teamsの見え方が想定と違う）

まずは「tmuxの中で claude を起動」できているか確認してください。
それでも意図通りにならない時だけ、公式ドキュメントの teammateMode を参照すると早いです。

画面分割された後、Ctrl + b を押して離しても、o や矢印が効かずフォーカスが移動しない

よくある原因がいくつかあります。上から順に試してみてください。

原因1：そもそも tmux の中にいない

  • tmux の中にいると、画面下に横長のバー（ステータス）が出ます。
  • バーが無い場合は tmux の外なので、次で戻れます（例）:
tmux a -t agent-demo

原因2：いま入力している場所（ペイン）にフォーカスが無い

  • まず、Terminalのそのペインを一度クリックしてから、もう一度 Ctrl + b →（離す）→ o を試してください。

原因3：特殊なモードに入っている（例：コピーモード）

  • 画面がスクロールできる状態になっていたり、キーがいつもと違う挙動のときは、まず q を押して抜けてから再度試してください。

どうしても直らない時（裏ワザ：tmuxの外からマウス操作をONにする）

Ctrl + b が不安定でも、別のTerminal（tmuxの外）から次を実行すると、クリックでペインを切り替えられるようになります。

tmux set -g mouse on

これで、ペインをクリックしてフォーカス移動できるようになります。

用語ミニ辞典（最小）

  • Terminal: 黒い画面に文字で操作するアプリ（macOS標準の「ターミナル」を指していますが、Cursor内蔵のターミナルやGhosttyなど他のアプリでもよい）
  • コマンド: Terminalに貼って実行する命令文
  • 環境変数: 機能のON/OFFスイッチみたいなもの（今回はチーム機能をONにする）
  • .zshrc: Terminal起動時に読まれる設定メモ（~/.zshrc）
  • Homebrew（brew）: macOSでアプリ/道具を入れるための「インストーラー」みたいなもの
  • tmux: Terminal画面を分割したり、作業を裏で動かし続ける道具
  • セッション: tmuxの「作業部屋」みたいなもの（名前で再接続できる）
  • デタッチ / アタッチ: tmuxを「一旦離れる / 戻る」操作（作業を止めずに離席できる）

参考リンク

Discussion