`--worktree` で複数セッションを並走させていて、ターミナルのペインも一緒に整えたい人向け
`claude --worktree` で複数セッションを並走させていて、毎回ターミナルを行ったり来たりするのが面倒な場面で、コマンドの後ろに `--tmux` を書き足して画面分割まで一緒に頼む。例: `claude -w feature-auth --tmux` で feature-auth 用の作業場所＋画面ペインがセットで立ち上がる
Claude Code を --worktree で2セッション3セッションと立ち上げていくと、ターミナルの画面切り替えが地味にしんどくなります。--tmux はその「画面の分割」までコマンドの後ろに書き足すだけで一緒にやってくれる仕組みで、worktree 1個 = 画面の1ペインみたいに対応づけて並べられます。
挙動は環境で変わります。iTerm2 で動かしているなら iTerm2 のペインが分かれ、そうじゃなければ従来の tmux が立ち上がる、という二段構え。名前に「tmux」と入っているのに必ずしも tmux が起動するわけではないのがハマりどころです。
噛み砕くと
会議室に複数のホワイトボードを並べて、テーマごとに人を割り当てるイメージ。--worktree がホワイトボード（独立した作業場所）を用意する役で、--tmux はそのホワイトボードを会議室の壁に並べて貼り出す役です。
1人で全部のホワイトボードを行き来していると、どれが何の話だったか見失います。最初から壁に並べておけば「左が認証機能、右がバグ修正」と一目で把握できる、その並べる作業を自動化してくれる、と思えば十分です。
大事な前提：単独で叩いても動かない、必ず --worktree とセット
公式の説明は1行で「Requires --worktree」とだけ書かれています。要するに claude --tmux だけ叩くとエラーで止まる作りで、画面分割だけ単独で頼むことはできません。
もう1つの前提が「対象フォルダで一度 claude を素で起動して、workspace trust の確認画面を1回通しておく」こと。これが済んでないと --worktree 自体が立ち上がらず、当然それに乗っかる --tmux も連鎖して失敗します。新しいフォルダで最初に --tmux を試して動かない時はだいたいこれです。
「家計簿アプリの feature-auth と bugfix-123 を同時並走で動かす」を例に手順を見る
題材は家計簿アプリ。「ログイン機能を作る作業」と「過去に出たバグ #123 を直す作業」を同じ日に並行で進めたい、という状況を想定します。両方とも同じプロジェクト（同じ Git の保管場所）の中の話ですが、ファイルが混ざると事故るので作業場所を分けたい。
ステップ1: まず素の claude で一度起動して trust を通す
家計簿アプリのフォルダに移動して、何もつけずに起動します。
$ cd ~/projects/kakeibo-app
$ claude初回だと「このフォルダを Claude Code に信頼させていいですか」みたいな確認が出ます。Yes で通す。これを済ませた瞬間に、このフォルダで --worktree と --tmux が解禁されます。確認が終わったら一度終了して大丈夫です。
ステップ2: 1つ目のセッション、feature-auth を立ち上げる
同じフォルダで、今度は worktree と tmux を一緒に指定します。
$ claude -w feature-auth --tmux裏で何が起きるか。.claude/worktrees/feature-auth/ という新しいフォルダが作られて、そこに家計簿アプリ一式が「feature-auth ブランチ」として展開されます。本体のフォルダとは独立なので、ここで何を編集しても元の作業フォルダには影響しません。
そして画面が分割される、というのが --tmux の仕事です。iTerm2 で動かしている人は iTerm2 のペインが横（か縦）に分かれます。素のターミナルや Linux で動かしている人は、ここで tmux が立ち上がります。
ステップ3: 2つ目のセッション、bugfix-123 を立ち上げる
別ターミナル（または分割された別ペイン）で、同じ家計簿アプリのフォルダから2発目を打ちます。
$ claude -w bugfix-123 --tmux同じ要領で .claude/worktrees/bugfix-123/ が作られて、bugfix-123 ブランチとして展開されます。画面はさらに分割されて、feature-auth と bugfix-123 が左右（または上下）に並ぶ形になります。
ステップ4: 画面の分かれ方を確かめる
ここで初心者がやりがちな勘違いがあります。「--tmux と書いたのに tmux が立ってない、壊れてる」と思ってしまうケース。
iTerm2 を使っているなら、tmux ではなく iTerm2 自身のペイン分割機能が呼ばれます。これは公式が「iTerm2 native panes を優先する」と明記している正しい挙動で、tmux のキー操作 Ctrl-b 系は効きません。iTerm2 のショートカット Cmd-D で分割、といった具合に iTerm2 流のキーで操作します。
逆に、どうしても従来通りの tmux を呼び出したいなら、こう書きます。
$ claude -w feature-auth --tmux=classicこれで iTerm2 を使っていても強制的に tmux が立ち上がり、Ctrl-b 系のキー操作で切り替えできるようになります。
ステップ5: 片方の作業が終わったら畳む
feature-auth の作業が一段落したらそのペインで Claude Code を終了します。worktree の作法に従って、保存していない変更があれば「残すか消すか」を聞かれます。残すならディレクトリと feature-auth ブランチが手元に保存され、消すならまるごと削除。
もう片方の bugfix-123 はそのまま動き続けます。片方を畳んでも残りに影響しないのが worktree+tmux 並走のいいところです。
つまり --tmux は何をしてくれるのか
- やってくれる:
--worktreeで作った独立作業場所と、それを表示するための画面分割をひとまとめに用意する。iTerm2 環境なら iTerm2 の分割、それ以外なら tmux の分割 - やってくれない:
--worktree抜きで画面分割だけ呼ぶことはできない。tmux を新規にインストールしてくれるわけでもないし、複数セッション間で会話履歴を共有してくれるわけでもない - 意味が薄い場面: そもそも1セッションしか動かさない時。worktree を使わずに普通に
claudeを立ち上げるだけの作業なら、画面分割を頼む理由がない
使いどころ3シナリオ（具体題材で再現）
シナリオ1: 機能開発とバグ修正を同じ日に進めたい家計簿アプリ
家計簿アプリで「ログイン画面の刷新」を進めている最中に、運用中のバージョンでバグ報告が来た。本体フォルダで作業中のものを途中保存せずに切り替えるのは面倒。claude -w bugfix-123 --tmux を別ペインで叩けば、ログイン画面の作業を続けたまま、別の画面でバグ修正用の隔離環境が立ち上がる。Claude Code が両方に1人ずつ常駐しているような状態を、自分でターミナルを移動せずに作れます。
シナリオ2: 同じ画面要件を3パターン試したい料理レシピサイト
料理レシピサイトのトップページを「写真メインのレイアウト」「文字情報メインのレイアウト」「動画埋め込みメインのレイアウト」の3案で見比べたい時。worktree でブランチを3本切って、それぞれを --tmux 付きで立ち上げると、画面上に3つのペインが並んで、3案を同時に Claude Code に書かせて見比べられます。終わったら採用しなかった2つを worktree ごと捨てるだけ。
シナリオ3: PR レビュー用に他人のブランチを引いてくる
GitHub に出ている変更提案 #1234 を手元で動かして確認したい。claude -w "#1234" --tmux で、worktree が PR の内容で立ち上がる + 画面が分割される、を一発でこなせます。自分の手元の作業ペインはそのまま残るので、レビューを終えたら #1234 のペインだけ閉じればいい。レビューと自分の作業の切り替えコストが消えます。
初心者が踏みやすい落とし穴
--worktreeを忘れてclaude --tmux単独で叩く。公式仕様で必ずセット指定が必要なので、単独だとエラーで止まります。「画面分割だけ頼みたい」はこのコマンドの守備範囲外- workspace trust を通していないフォルダで初手
--tmux。--worktree側がそもそも起動を拒否するので、tmux 以前で失敗します。新規フォルダでは必ず素のclaudeを1回挟む - iTerm2 を使っているのに「tmux が起動しない、壊れてる」と思い込む。iTerm2 環境では tmux ではなく iTerm2 ネイティブのペイン分割が呼ばれます。これは仕様。tmux を強制したいなら
--tmux=classicを明示 - すでに tmux セッションの中で
claude -w 名前 --tmuxを叩く。tmux の中にさらに tmux が立ち上がる入れ子構造になる。この状態の挙動は公式ドキュメントに明示がないので、iTerm2 環境でない場合は--tmux=classicを使うか、外側の tmux を使わずに叩く方が確実 - Windows ネイティブ環境での挙動は公式ドキュメントに記載がない。tmux も iTerm2 も macOS/Linux 向けのツールなので、Windows で動かしたい場合は WSL2（Windows Subsystem for Linux）の Linux 環境から試すのが現時点での現実的な選択肢。ただし公式サポート状況は別途確認が必要
- worktree を畳まずに次々と
--tmux付きで増やす。.claude/worktrees/配下にどんどんフォルダが溜まります。.gitignoreに.claude/worktrees/を入れておくのを忘れず、不要なものはこまめに畳む - 1人で全ペインを同時操作しようとする。Claude Code は各ペインで独立に動きますが、人間の集中力は1つ。並走させるのは「ビルドを待っている間にもう片方を進める」程度の使い方が現実的
書き方
claude -w <名前> --tmux
claude -w <名前> --tmux=classic # 従来の tmux を強制やってみるとこうなる
入力
$ claude -w feature-auth --tmux出力例
（iTerm2 環境の場合）
→ .claude/worktrees/feature-auth/ が作られて feature-auth ブランチで起動
→ iTerm2 のペインが分割されて、新しい Claude Code セッションがそのペインで開く
（素のターミナル/Linux の場合）
→ .claude/worktrees/feature-auth/ が作られて feature-auth ブランチで起動
→ tmux が立ち上がって、その中のペインで新しい Claude Code セッションが開くこのページに出てきた言葉
- worktree
- Git の機能で、同じプロジェクトを別々のフォルダに同時に展開して、それぞれ違うブランチで作業できる仕組み。Claude Code の <code>--worktree</code> はこれを使って作業場所を切り分ける
- workspace trust
- そのフォルダの中身を Claude Code に触らせていいかを確認する画面。初回起動時に1回だけ出る。通していないと <code>--worktree</code> ごと失敗する
- tmux
- 1つのターミナル画面を縦横に分割して、複数の作業を同時に進められるようにする仕組み。Linux/macOS で広く使われる
- iTerm2
- macOS で人気のターミナルアプリ。標準のターミナルより高機能で、画面分割機能を自前で持っている
- ペイン
- 1つのターミナル画面を分割した時の、それぞれの小さい領域
- ブランチ
- Git で「ある時点から分岐した別の作業ライン」のこと。feature-auth ブランチで作った変更は、メインのラインには勝手に混ざらない
- --tmux=classic
- iTerm2 環境でも従来通りの tmux を強制起動するための書き方
- PR
- Pull Request の略。GitHub で「この変更を本体に取り込んでほしい」と提案する仕組み