はじめに
Claude Code のマルチエージェント機能(Agent Teams)を tmux の画面分割と組み合わせて使うと、複数の AI が役割分担しながら並列で作業する様子を一画面で確認できます。本記事ではその環境を macOS 上で構築する手順をまとめます。
実質的に必要なのは tmux + Claude Code + 設定ファイル 2 つ だけで、Unix 系 OS である macOS なら追加の仮想環境などは不要です。
※ 環境構築のみの記事です。実際の運用(要件定義 → 実装の流れ)は次回まとめます。
用語のおさらい
- tmux: 1 つのターミナル内で画面分割(split panes)できるツール
- Claude Code: Claude をターミナルから使うための CLI ツール
- マルチエージェント (Agent Teams): Claude Code の実験的機能で、複数の AI が役割分担して同時に作業する仕組み
- split panes: 画面を複数に分割して同時表示すること
動作確認環境
- macOS (Apple Silicon, MacBook Air M4)
- Homebrew 導入済み
- tmux 3.5a
- git 2.48.1
- Claude Code 2.1.119
- Claude Max サブスクリプション
全体の流れ
Homebrew で tmux と git を確認
↓
Claude Code をインストール
↓
初回起動と認証
↓
~/.claude/settings.json でマルチエージェントを有効化
↓
~/.claude/CLAUDE.md で運用方針を記述
↓
tmux 起動 → claude 起動 → 動作確認1. tmux と git の準備
未導入なら Homebrew で入れます。
brew install tmux gitバージョン確認だけ済ませておきます。
tmux -V
git --version2. Claude Code のインストール
公式のインストールスクリプトを実行します。
curl -fsSL https://claude.ai/install.sh | bashPATH を通します。macOS のデフォルトシェルは zsh なので ~/.zshrc に追記します。
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrcbash を使っている場合は ~/.bash_profile に書き換えてください。確認は echo $SHELL で行えます。
インストール確認:
claude --version
# 2.1.119 (Claude Code)3. 初回起動と認証
claude コマンドで起動します。
claude順に以下のセットアップ画面が表示されます。
3-1. テキストスタイル選択
最初にテーマを選びます。Auto (match terminal) が無難ですが、お好みで選択してください。
3-2. ログイン方法選択
サブスクリプション利用なら Claude account with subscription、API キー利用なら Anthropic Console account を選択します。
選択するとブラウザに認証用 URL が開くので、ログイン後に表示されるキーをターミナルに貼り付けます。
3-3. セキュリティ注意事項
認証完了後、Claude Code 利用時の注意事項が表示されます。一読して Enter で進みます。
3-4. ターミナル設定の有効化
Option+Enter での改行や Visual Bell が有効になる推奨設定です。Yes, use recommended settings を選択します。
3-5. ⚠️ つまずきポイント 1: 作業フォルダはホームディレクトリ直下を避ける
次に表示される「フォルダ信頼確認」では、Claude Code が読み書きするスコープを決めます。ホームディレクトリ(/Users/<username>)で起動するとそこ全体が作業対象になるため、.ssh や .aws などの機密情報まで Claude Code のスコープに入ってしまいます。
専用の作業ディレクトリを作ってからやり直すのが無難です。
# 一度 No, exit で抜けてから
mkdir ~/works
cd ~/works
claude4. settings.json でマルチエージェントを有効化
ここがマルチエージェント環境の 本丸 です。~/.claude/settings.json を編集します。
初回認証後にディレクトリは作成済みのはずですが、無ければ mkdir -p ~/.claude で作成します。すでに theme などの最小設定が入っている場合があるので、cat ~/.claude/settings.json で中身を確認してから編集してください。
ヒアドキュメントで一発上書きするのが確実です(viで編集する場合は :set paste でペースト崩れを回避するのを忘れずに)。
cat > ~/.claude/settings.json << 'EOF'
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
},
"theme": "auto",
"defaultMode": "acceptEdits",
"disableBypassPermissionsMode": "disable",
"permissions": {
"ask": [
"Bash(git branch -d *)",
"Bash(git branch -D *)",
"Bash(git push --delete *)",
"Bash(git tag -d *)",
"Bash(git push --force *)",
"Bash(git push -f *)",
"Bash(git reset --hard *)",
"Bash(git clean -fd *)",
"Bash(git clean -xfd *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}
EOFJSON が壊れていないか確認しておきます。
python3 -m json.tool ~/.claude/settings.json各設定の意味
| キー | 役割 |
|---|---|
env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS | マルチエージェント機能を有効化する。これを "1" にしないと Agent Teams は動かない |
defaultMode | acceptEdits でファイル編集を自動承認(逐一の確認プロンプトを減らす) |
disableBypassPermissionsMode | 権限バイパスモードを無効化(disable を指定) |
permissions.ask | 巻き戻しが大変な git コマンド実行前に人間に確認を求める |
permissions.deny | .env や secrets/ 配下のような機密ファイルを読み込ませない |
5. CLAUDE.md でマルチエージェント運用方針を記述
settings.json が「Claude Code の動作設定」なら、CLAUDE.md は「Claude への指示書」です。どういう場面でマルチエージェントを使うべきか をここに書いておきます。
cat > ~/.claude/CLAUDE.md << 'EOF'
# 開発方針
## 応答言語
- ユーザーが別言語を指定しない限り、日本語で回答する。
## 基本ワークフロー
- 曖昧な点は推測せず、ファイルや実行結果を確認する。
- 破壊的、または巻き戻し困難な操作の前には、必ずユーザーの明示同意を取る。
- 最終報告では、変更点・確認内容・未検証事項を簡潔にまとめる。
## マルチエージェント運用
- 並列調査や役割分担が有効な場合は、agent team を作成してよい。
- 調査・レビュー・比較検討のように独立して進められる作業では、複数の teammate に分担して進める。
- 実装を伴う大きな作業では、必要に応じて team の人数や役割を増やしてよい。
- team を作る場合は、各 teammate の役割が重複しないように分ける。
- split panes を使える環境では、team 作成時は split panes を優先する。
EOF6. tmux で動作確認
作業ディレクトリで tmux セッションを起動します。
cd ~/works
touch test.txt
tmux new -s claude-team-test画面下部に緑色のステータスバーが出れば tmux に入った状態です。そのまま Claude Code を起動します。
claudetmux 内で Claude Code が起動した状態がこちら。画面下部の緑色のステータスバー([claude-team-test])で tmux セッション内であることが分かります。
マルチエージェントを呼び出すプロンプト
以下のプロンプトを Claude Code に投入します(改行は Option+Enter、もしくは複数行をクリップボードからまるごと貼り付け)。
表示確認のため、このタスクは agent team を作って進めてください。
split panes を使える場合は split panes を優先してください。
ファイル変更はしないでください。
独立して進められる観点ごとに役割を分け、並列に調査してください。
1人は現在のディレクトリ構成と主要ファイルを確認してください。
もう1人は test.txt と関連する設定・状態を確認してください。
各 teammate は短く結果をまとめ、最後に lead が統合して報告してください。うまくいくと 画面が複数のペインに分割 され、それぞれのペインで別のエージェントが並列に動き出します。
各 teammate(@dir-scout、@file-inspector)に役割が割り振られ、左側で @team-lead が指示出しと統合報告を行っているのが見て取れます。
つまずきポイントとその対処
構築〜動作確認の中で遭遇しやすいポイントをまとめます。
つまずき 1: 軽いタスクだと split panes に分割されない
タスクが軽い場合、マルチエージェント自体は内部で動いていても画面上は分割されずバックグラウンド処理になる ことがあります。
確実に画面分割を再現したい場合は、プロンプト側で
必ず split panes で分割して進めてと明示するのが有効です。settings.json(機能スイッチ)・CLAUDE.md(運用方針)・プロンプト(都度の指示)、この 3 層すべてに split panes の意図が一貫して通っていると安定します。
つまずき 2: ホームディレクトリで起動してしまった
初回起動でうっかり Yes, I trust this folder を押してホームディレクトリを信頼スコープに入れてしまった場合、/exit で抜けてから別の作業ディレクトリで起動し直しましょう。Claude Code は信頼したフォルダを内部で記録していますが、作業スコープは「起動したディレクトリ」で決まる ので、別のディレクトリで起動すれば問題ありません。
つまずき 3: settings.json がすでに存在していて上書きが怖い
初回認証時に ~/.claude/settings.json が自動生成され、theme などが書き込まれていることがあります。ファイルを上書きする前に必ず cat で中身を確認 し、既存設定をマージする形で編集してください。
つまずき 4: settings.json の JSON 構文エラー
vi で編集した際に保存コマンドの :q! がそのまま本文に書き込まれてしまう、ペースト時の自動インデントで構造が崩れる、といった事故が起きやすいファイルです。Claude Code 起動時に以下のエラーが出たら JSON 構文を疑いましょう。
Settings Error
/Users/<username>/.claude/settings.json
└ Invalid or malformed JSON対処は本記事「4. settings.json でマルチエージェントを有効化」のヒアドキュメント例で上書きすれば一発で直ります。python3 -m json.tool で構文チェックを習慣化しておくと安心です。
つまずき 5: claude コマンドが見つからない
zsh: command not found: claudePATH が通っていません。~/.zshrc に export PATH="$HOME/.local/bin:$PATH" を追記して source ~/.zshrc を実行してください。bash を使っているなら書き込み先は ~/.bash_profile です。
設定ファイルの整理
役割が混乱しがちなので表で整理します。
| ファイル | 役割 | 例 |
|---|---|---|
~/.claude/settings.json | Claude Code の動作設定 | マルチエージェントの有効化、権限設定、デフォルトモード |
~/.claude/CLAUDE.md | Claude への指示書(共通) | 応答言語、運用方針、役割分担の基本ルール |
| プロンプト | 都度の具体的な指示 | 「split panes で進めて」「4 人体制で」など |
機能スイッチは settings.json、振る舞いの方針は CLAUDE.md、その場の指示はプロンプト、と層を分けて考えると整理しやすいです。
まとめ
macOS で Claude Code のマルチエージェント環境を構築するために必要なのは以下の 4 ステップです。
brew install tmux git- Claude Code のインストールと認証
~/.claude/settings.jsonにマルチエージェントを有効化する設定を追記~/.claude/CLAUDE.mdに運用方針を記述
これで tmux new -s <セッション名> → claude → split panes 動作確認まで再現できました。
次回予告
環境ができただけではただの箱なので、次回は 実際にこの環境を使って Web サービスを開発する ところまでやってみたいと思います。
具体的には、
planモードでマルチエージェントによる 要件定義 を行う- 同じ体制で 実装フェーズ に進む
- マネージャー / フロントエンド / バックエンド / QA の 4 人体制で進行
- 完成物の納品とレポートの自動生成
までやってみる予定です。実際に「マネージャーから差し戻しが入る」「QA が他の teammate の意見を取りまとめる」といった役割分担がどこまで機能するか、検証していきます。
おわり。
コメント