Claude Codeのマルチエージェント機能を使うために、tmux環境を整えた話

Claude Codeを日常的に使っていて、「1つのタスクを複数のAIに同時に任せられたらもっと早くなるのでは？」と思っていた。調べてみると、Claude Codeにはサブエージェントとエージェントチームという2つの並列処理の仕組みがあって、エージェントチームを画面分割で動かすにはtmuxというツールが必要らしい。

クラスメソッドさんの「Windows 11（WSL×Arch Linux×tmux）でClaude Codeのマルチエージェント開発環境を1から構築してみた」を参考にしたが、あの記事はArch Linuxを1から入れるところからの手順。自分のWSL2 + Ubuntu環境なら、もっとシンプルにできるはず。

ところがtmuxを調べていくと、WezTermやターミナルのGPUレンダリングなど聞き慣れない概念が出てきて混乱した。結局そこを整理するところから始まった。

この記事では、tmuxとは何なのか・なぜ必要なのかを理解するところから、Claude Codeのマルチエージェント機能を使えるようになるまでをまとめる。

やってみた理由

Claude Codeでブログ記事の作成やコードの修正をしていると、「ここを調べている間に、あっちも並行で進めてくれたら……」と思う場面が増えてきた。

調べてみると、Claude Codeには「エージェントチーム」という機能があって、複数のAIが同時に作業できるらしい。しかもtmuxを使えば、全員の作業を画面分割で同時に見られるという。

まずはtmuxを入れて、マルチエージェント環境を作ってみることにした。

やったこと

まず「自分がどこで作業しているか」を理解する

tmuxを入れる前に、自分の環境の構造を把握しておく必要がある。ここがわからないと、tmuxがどの階層で動くのか、なぜ必要なのかが見えてこない。

環境の階層構造（外側→内側）

Windows 11（ホストOS）
  └─ WSL2（軽量Linux仮想マシン）
       └─ Ubuntu（Linuxディストリビューション）
            ├─ tmuxサーバー ← 今回入れるのはここ
            ├─ Docker
            │    ├─ ComfyUIコンテナ
            │    └─ ollamaコンテナ
            └─ Claude Code等のプロセス

階層	役割
Windows 11	ホストOS。GPU（RTX 5090）のドライバが動く場所
WSL2	Windows上で動く軽量Linux仮想マシン。GPUパススルーでCUDA利用可能
Ubuntu	WSL2上で動くLinuxディストリビューション（OSの中身）
ターミナルエミュレータ	Ubuntu内のシェルを表示するアプリ（Windows Terminal等）
tmux	ターミナル内で動く「仮想画面分割・セッション管理」ツール

tmuxはUbuntuの層で動く。Dockerの中ではない。Ubuntu上にいるからこそ、Claude Codeの実行もDockerコンテナの操作も、全部まとめて管理できる。

tmuxを調べていて混乱したこと

tmuxを調べていると「WezTerm」「ターミナルのGPUレンダリング」「WezTermでVSCodeのようにする」といった情報が出てきて、何が何なのかわからなくなった。ここを整理しておく。

WezTermとtmuxは同じもの？→ 違う

役割が根本的に違う。

	WezTerm	tmux
正体	ターミナルエミュレータ（画面を映すテレビ）	ターミナルマルチプレクサ（テレビの中で画面分割する仕組み）
画面分割	できる	できる
タブ	できる	できる（ウィンドウ）
セッション維持	できない	できる
動作場所	Windows/Mac上のGUIアプリ	Linux/WSL内のCUIツール

機能が一部重なるから比較されるが、レイヤーが違うので本来は「選ぶ」ものではなく併用もできる。

判断基準はひとつ。セッション維持が必要かどうか。SSH接続やWSL2で長時間プロセスを走らせて、切断しても作業が消えないでほしいならtmuxが必要。ローカルで作業するだけで切断されても困らないならWezTermだけで十分。

「WezTermでVSCodeのようにする」とは？

WezTermだけでVSCode風の開発環境を再現するという意味。タブ、ペイン分割、Neovimを組み合わせて「VSCode（GUI）を捨てて、ターミナルだけで全部やる」というスタイル。

今の自分には不要。VSCodeは使えていてClaude Codeとの連携もできている。WezTerm + Neovimの環境構築は「ツール沼」の典型で、数日〜数週間溶ける割に、得られるメリットは「見た目がカッコいい」「軽い」程度。ブログ記事やAI実験の前進には繋がらない。

「ターミナルのGPUレンダリング」とは？

ターミナルエミュレータが文字の描画にGPUを使うこと。AIの推論やCUDAとは無関係で、純粋に「文字表示の高速化・滑らかさ」の話。

Windows Terminal：デフォルトでGPUレンダリング有効（DirectX）
Alacritty / WezTerm / Kitty：OpenGL/Vulkan等でGPU描画する軽量ターミナル

GPUレンダリング対応ターミナルは、大量のログが流れたりtmuxで4〜6画面分割して同時出力がある場面でカクつかない。ただし普段のコマンド操作程度なら体感差はほぼゼロ。

RTX 5090のGPUリソースはComfyUIやollama等のAI処理に使うのが本命。ターミナルのGPUレンダリングはVRAMをほぼ消費しない（数十MB程度）ので共存は問題ない。

結論：tmuxだけ入れればいい。ターミナルはWindows Terminalのままで問題ない。

tmuxはなぜ必要なのか

tmuxが「セッション維持」できる理由を理解すると、なぜマルチエージェントに必要なのかがわかる。

普通のターミナルの場合

Windows Terminal → WSL2のシェル（bash） → 実行中のプロセス

この3つは親子関係で繋がっている。Windows Terminalを閉じると、子であるシェルが死に、孫であるプロセスも道連れで死ぬ。

tmuxがいる場合

Windows Terminal → tmux（クライアント） → tmuxサーバー → シェル → プロセス

ポイント：tmuxサーバーはWSL2内で独立したプロセスとして動いている。Windows Terminalとは直接の親子関係がない。

だからWindows Terminalを閉じても：

tmuxクライアント（画面表示役）だけが消える
tmuxサーバーはWSL2内で生き続ける
シェルもプロセスもそのまま動き続ける
再度接続（tmux attach）すれば、元の画面がそのまま出る

一言でまとめると：tmuxは「画面を映す役」と「作業を動かす役」を分離している。だから画面を消しても作業が止まらない。

注意点：WSL2自体がシャットダウンされるとtmuxサーバーも消える。Windows Terminalを閉じただけならWSL2はバックグラウンドで動き続けるので大丈夫だが、wsl --shutdown やPC再起動をするとtmuxのセッションも消える。tmuxが守れるのは「うっかりターミナルを閉じた」「SSH切断」レベルの事故。

tmuxのインストール

WSL2のUbuntu上でコマンド1行。

sudo apt update && sudo apt install tmux -y

tmuxの基本操作

コマンド	意味
`tmux`	新しいセッション開始
`tmux new -s 名前`	名前付きセッション開始
`tmux attach`	既存セッションに再接続
`tmux ls`	セッション一覧確認

セッション内の操作は、すべて Ctrl+b を先に押してからキーを押す。

キー操作	意味
`Ctrl+b` → `d`	セッションから離脱（デタッチ）。作業は裏で続く
`Ctrl+b` → `%`	画面を左右分割
`Ctrl+b` → `"`	画面を上下分割
`Ctrl+b` → `矢印キー`	分割画面間の移動
`Ctrl+b` → `x`	現在のペインを閉じる

まずは tmux で起動して Ctrl+b → d でデタッチ、tmux attach で戻る。この流れだけ試せば感覚がつかめる。

tmuxのおすすめ設定

tmuxをインストールしたら、設定ファイルを作っておくことを強く推奨する。デフォルトのままだと、マウススクロールが効かなかったり、操作がやりにくい。

~/.tmux.conf を作成する。

# マウス操作を有効化（スクロール、ペイン選択、リサイズ）
set -g mouse on

# スクロールで遡れるログの行数（デフォルト2000→50000に）
set -g history-limit 50000

# 色の設定（Claude Codeの表示色がおかしくならないように）
set -g default-terminal "tmux-256color"
set -ga terminal-overrides ",*256col*:Tc"

# ESCキーの遅延を短縮（デフォルト0.5秒→10ミリ秒）
set -sg escape-time 10

# ウィンドウ番号を1始まりに（キーボード配置的に直感的）
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

# ペイン分割を直感的なキーに変更
bind | split-window -h -c "#{pane_current_path}"
bind - split-window -v -c "#{pane_current_path}"

# 設定リロード（Prefix + rで再読み込み）
bind r source-file ~/.tmux.conf \; display "Reloaded!"

設定を反映する。

tmux source-file ~/.tmux.conf

特に重要なのは set -g mouse on。これがないとtmux内でマウススクロールが効かず、過去のログを遡るのに Ctrl+b → [ でコピーモードに入る必要がある。mouse on にしておけばマウスホイールでそのまま過去ログをスクロールできる。

tmux-resurrect / tmux-continuum（オプション）

tmuxのプラグインで、PC再起動後もセッションを復元できるものがある。

tmux-resurrect：セッションを手動で保存・復元
tmux-continuum：resurrectを自動化。PC再起動後もセッション復元可能

これを入れれば「PC再起動でtmuxセッションが消える」問題が解決できる。ただしClaude Codeのプロセス自体が復元されるわけではないので、あくまで「ペインの配置とディレクトリが戻る」レベル。必要になったら入れればいい。

Claude Codeのインストール

tmuxの次はClaude Code本体。WSL2のUbuntu上でインストールする。

curl -fsSL https://claude.ai/install.sh | bash

PATHが通っていない場合は .bashrc に追記。

export PATH="$HOME/.local/bin:$PATH"

バージョン確認。

claude --version

エージェントチーム機能にはv2.1.32以上が必要。

サブエージェントとエージェントチームの違い

環境が整ったところで、Claude Codeの2つの並列処理の仕組みを理解する。

サブエージェント（Sub-agents）

サブエージェントは、メインのClaude Codeセッション内で動く「部下」のようなもの。メインのAIが「このファイル調べておいて」と指示を出して、結果だけ受け取る。

メインセッションの中で動く（別ウィンドウは不要）
結果をメインに返すだけ。サブエージェント同士は会話しない
メインのコンテキストウィンドウを汚さない（調査結果だけ返ってくる）
トークン消費が少ない
実は普段のClaude Codeでも裏で自動的に使われている

Claude Codeには最初からビルトインのサブエージェントがいる。

名前	役割
Explore	コードベースの検索・調査（読み取り専用）
Plan	計画モードでの調査・情報収集
General-purpose	複雑なマルチステップのタスク

普段Claude Codeに「このコード調べて」と言うと、裏でExploreサブエージェントが動いていたりする。意識しなくても使っている機能だ。

エージェントチーム（Agent Teams）

エージェントチームは、複数のClaude Codeインスタンスが独立して動く「チーム」。リーダーが仕事を割り振り、メンバーが並行作業する。

各メンバーが独立したClaude Codeセッションを持つ
メンバー同士が直接メッセージをやり取りできる
共有タスクリストで進捗管理する
リーダーが統括し、結果をまとめる
トークン消費が多い（メンバー数に比例）

比較表

	サブエージェント	エージェントチーム
動作場所	メインセッション内	独立した複数セッション
コミュニケーション	結果をメインに返すだけ	メンバー同士が直接やり取り
調整方法	メインが全て管理	共有タスクリストで自律的に
向いている作業	結果だけ欲しい集中タスク	議論・協力が必要な複雑作業
トークンコスト	低い	高い（メンバー数×）
表示モード	メインターミナル内	in-process / split panes（tmux）

ざっくり言うと、サブエージェントは「調べ物を頼む派遣スタッフ」、エージェントチームは「プロジェクトチーム」。

セキュリティ設定（これが重要）

エージェントチームを有効にする前に、セキュリティの設定をしっかりやっておく必要がある。なぜなら、エージェントチームのメンバーはリーダーの権限設定を引き継ぐからだ。

リーダーが --dangerously-skip-permissions で起動したら、全メンバーもパーミッションチェックなしで動く。逆に言えば、リーダーの設定をちゃんとしておけば、全メンバーに反映される。

~/.claude/settings.json に以下を設定する。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "ask": [
      "Bash(git push --force *)",
      "Bash(git push -f *)",
      "Bash(git reset --hard *)",
      "Bash(git clean -fd *)",
      "Bash(git clean -xfd *)",
      "Bash(git branch -D *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

設定のポイント。

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1"：エージェントチーム機能を有効化する（デフォルトは無効）
permissions.ask：危険なgit操作は実行前に確認を求める。force pushやhard resetを間違って実行されたら取り返しがつかない
permissions.deny：.envファイルやsecretsフォルダは読み取り禁止。APIキーやパスワードがAIに渡るのを防ぐ

ここで注意。エージェントチームは実験的機能（experimental）で、デフォルト無効。有効にするということは、複数のAIが同時にファイルを編集する可能性があるということ。permissions設定を省略すると、メンバーが危険な操作を確認なしで実行できてしまう。

エージェントチームの使い方

起動方法

tmuxのsplit panesモードで使うなら、まずtmuxセッション内でClaude Codeを起動する。

# tmuxセッションを作成
tmux new -s work

# Claude Codeを起動
claude

tmuxセッション内で起動すると、エージェントチームが自動的にsplit panesモードになる（teammateMode: "auto" がデフォルト）。tmux外で起動するとin-processモードになる。

表示モードの選択

モード	特徴	要件
in-process	全メンバーが1つのターミナルで動く。Shift+↓で切り替え	なし（tmux不要）
split panes	各メンバーが別ペインで見える。全員の動きが同時に見える	tmuxまたはiTerm2

~/.claude.json で固定もできる。

{
  "teammateMode": "in-process"
}

または起動時に指定。

claude --teammate-mode in-process

tmuxなしでもエージェントチームは使える。in-processモードならターミナルは何でもいい。tmuxがあると「全員の動きを同時に見られる」split panesモードが使えるのが利点。

チーム作成のプロンプト例

自然言語で指示するだけでチームが作られる。

コードレビュー（おすすめの入門用途）

PR #42をレビューするエージェントチームを作成して。
- セキュリティ観点のレビュアー
- パフォーマンス観点のレビュアー  
- テストカバレッジのレビュアー
3人でレビューして、結果をまとめて。

デバッグ（仮説を競わせる）

ユーザーがログイン後すぐにセッションが切れる問題を調査して。
エージェントチームを作って、5人のメンバーにそれぞれ別の仮説を調査させて。
お互いの仮説を否定し合って、科学的な議論のように最も確からしい原因を突き止めて。

並列開発

以下のモジュールをリファクタリングするチームを作成して。4人のメンバーで並列実行。
各メンバーはSonnetモデルを使って。

チームの操作

操作	方法
メンバー切り替え	Shift+↓（in-processモード）
メンバーに直接指示	切り替えてからメッセージ入力
タスクリスト表示	Ctrl+T
メンバー停止	リーダーに「○○を停止して」と指示
チーム解散	リーダーに「チームをクリーンアップして」と指示

重要なルール。

チームの解散は必ずリーダーから行う（メンバーからやるとリソースが残る可能性）
解散前に全メンバーを停止する
1セッションにつき1チームまで
メンバーがさらにチームを作ることはできない（ネスト不可）
同じファイルを複数メンバーが同時に編集すると上書きされる。作業範囲を明確に分けること

チームサイズの目安

3〜5人で始めるのがベスト。多すぎると調整コストが増えて逆に遅くなる
メンバー1人あたり5〜6タスクが目安
独立した15タスクがあるなら、3人チームがちょうどいい

サブエージェントのカスタマイズ

サブエージェントは自作もできる。.claude/agents/ にMarkdownファイルを置くだけ。

---
name: security-reviewer
description: セキュリティ観点でコードをレビューする
tools: Read, Glob, Grep
model: sonnet
---

あなたはセキュリティレビューの専門家です。
コードを分析し、OWASP Top 10を中心にセキュリティ上の問題を指摘してください。

配置場所	スコープ	優先度
`~/.claude/agents/`	全プロジェクト共通	低
`.claude/agents/`（プロジェクト内）	そのプロジェクトのみ	高

自作サブエージェントはエージェントチームのメンバーとしても使える。

security-reviewerエージェントタイプを使ってチームメイトを作成して。認証モジュールを監査して。

結果

tmuxのインストールと設定、Claude Codeのセキュリティ設定、合わせて30分もかからなかった。

tmuxのsplit panesモードでは、複数のClaude Codeが画面分割で同時に動く様子が見える。掃除機をかけている間にAIチームがコードを調査してくれる、という使い方ができる。

ただし、日常使いでは「サブエージェント」のほうが出番が多い。コードの調査や分析なら、わざわざチームを組むよりサブエージェントに任せるほうがトークンも節約できて効率的。エージェントチームは「レビュー」「デバッグ調査」「並列開発」のような、明確に役割分担できるタスクで威力を発揮する。

うまくいった点

tmuxの理解が深まった。階層構造を整理したことで、tmuxがどこで何をしているのかがクリアになった
環境構築がシンプルだった。WSL2 + Ubuntuがあれば apt install tmux と設定ファイル変更だけ
サブエージェントとエージェントチームの使い分けが明確になった。結果だけ欲しいならサブエージェント、議論させたいならチーム
WezTerm等のツール沼を回避できた。目的（マルチエージェント）に必要なもの（tmux）だけ入れた

失敗・課題

tmuxの初期設定が罠。mouse on を設定しないとスクロールが効かない。デフォルトで有効にしておいてほしい
エージェントチームはトークン消費が大きい。メンバー数に比例して消費量が増えるので、サブスクリプションの利用上限にすぐ到達する。気軽に使うとあっという間に上限が来る
実験的機能（experimental）。セッション復元が効かない、タスクのステータスがずれることがある、シャットダウンが遅いなど、まだ荒削りな部分がある
split panesモードはVS Codeのターミナルでは非対応。tmuxかiTerm2が必要

次にやること

自作サブエージェントを作って、プロジェクト固有のレビューやチェックを自動化する
エージェントチームを使った実際の開発タスク（フロント・バック・テストの3人チーム）を試す
tmux-resurrect / tmux-continuumを導入して、PC再起動後もセッション復元できるようにする