エージェントビュー

エージェントビューは、claude agents で開く1画面の管理画面です。バックグラウンドで動くセッションが「作業中・入力待ち・完了」のどれかを一覧し、新しい作業の投入、状況の確認、必要なときだけの介入ができます。各セッションは端末をつないでいなくても動き続ける完全な Claude Code の会話で、開いて返信し、離れることもできます。

• 独立した作業（バグ修正・PR レビュー・不安定なテストの調査など）を行として投げて、別の作業を続けられる
• 行を選んで Space を押すと、全文を開かずに最新の出力や質問を見て返信できる（ピーク）
• 動いている会話に入る（アタッチ）と、通常の対話セッションとして操作できる
• 開いている会話は /bg か ← でバックグラウンドに送れる
• サブエージェント・エージェントチーム・worktree との使い分けは並列作業の選び方を見てください

最初の一巡#

1. シェルで claude agents を実行します。未承認のディレクトリでは、先にワークスペースの信頼ダイアログが出ます（断ると終了します）。
2. 下の入力欄にやりたいことを書いて Enter を押します。新しいバックグラウンドセッションが始まり、行として現れます。もう1つ書いて Enter を押すと、後続の指示ではなく2つ目のセッションが並行して始まります。
3. 行を矢印キーで選び、Space でピークパネルを開きます。返信を入力して Enter で送れます。
4. Enter か → でアタッチして会話全体に入ります。空のプロンプトで ← を押すと一覧へ戻ります。
5. すでに開いているセッションを移すには、その中で /bg を実行するか、空のプロンプトで ← を押します。

Esc でシェルへ戻ります（← でバックグラウンドにして開いた場合は、元の会話へ戻ります）。離れても、セッションは動き続けます。

通常の claude セッションでは、プロンプト下の ← の表示が、入力待ちのバックグラウンドエージェント数（← 2 agents など）を数えます。99 を超えると 99+ です。表示はフォーカス中で約10秒ごとに更新され、色の点滅は prefersReducedMotion 設定がオンなら止まります。スクリーンリーダーモードでは表示されません。

既定でエージェントビューを開く#

引数なしの claude でエージェントビューを開くには、/config の「Open agents view by default」をオンにするか、defaultToAgentsView を直接設定します。

/config defaultToAgentsView=true

通常のセッションを始めるときは、claude "fix the login test" のようにプロンプトを渡します。戻すには /config defaultToAgentsView=false を実行します。

一覧の見方#

claude agents は端末全体を使い、状態ごとにグループ化して表示します。固定したものと入力待ちのものが上に来ます。各行は、名前・現在の動き・経過時間（作成からの時間。終わったセッションは実行にかかった時間で止まる）を示します。名前は、そのセッションの /color の色で表示されます。

• 既定では、すべてのプロジェクトで始めたバックグラウンドセッションが全部出ます
• 範囲を絞るには claude agents --cwd ~/projects/my-app とします。そのディレクトリ以下で始まったセッション（.claude/worktrees/ に移ったものを含む）だけが出ます
• 別の端末で開いている対話セッションは、バックグラウンドにするまで出ません
• セッションが起こしたサブエージェントやチームメイトは、別の行になりません

Pinned
  ✽ clawd walk cycle          Drawing the walk-cycle sprite frames          3m
Ready for review
  ∙ jump physics              Opened PR with collision fix                 #2048  2h
Needs input
  ✻ power-up design           double jump or wall climb?                    1m
Working
  ✽ collision detection       Adding swept-AABB checks to CollisionSystem   2m
Completed
  ✻ title screen              result: menu, options, and credits done       9m
  … 6 more

状態のアイコン#

行頭のアイコンの色とアニメーションが状態を示します。

/install-github-app や /mcp の設定一覧のように、端末にアタッチしないと動かないコマンドは、アタッチなしだと「Needs input」で待ちます。アタッチして再実行すると続けられます（/mcp reconnect <server>・/mcp enable・/mcp disable はアタッチ不要）。

アイコンの形は、プロセスが動いているかを示します。

行の右端の #N や !N は、状態ではなく、セッションの PR（GitLab ではマージリクエスト）へのリンクです。エージェントビューを開いている間、端末のタブ名は 2 awaiting input · claude agents のように入力待ちの数を示します。

エージェントビューを開いている間、ローカルのバックグラウンドセッションが入力待ちになる・完了する・失敗すると、設定した端末通知チャネル（preferredNotifChannel）で通知されます。Notification フック（agent_needs_input または agent_completed）も発火します。/loop のようにスケジュールで動くセッションは、入力待ちのときだけ通知します。

セッションの状態は自動更新やスーパーバイザーの再起動をまたいでディスクに残り、マシンのスリープ中も保たれます。シャットダウンでは止まります（後述）。

行の要約#

行の1行要約は Haiku クラスのモデルが作ります。作業中は、モデルを呼ばずにセッション自身の最近の出力から最大15秒に1回更新し、ターンの終了時に新しい要約を作ります。長いターンの間は数分ごとに書き直します。ディレクトリでグルーピングしているときは、要約の頭に Needs input · ... のように状態が付きます。

要約の生成は、通常のプロバイダー経由の短いリクエストで、セッション本体と同じデータ利用条件で課金・処理されます。Haiku クラスのモデルがないサードパーティのプロバイダーやゲートウェイでは、セッションのメインモデルが使われます。選ぶには ANTHROPIC_DEFAULT_HAIKU_MODEL を設定します。

PR の状態#

セッションが PR を開くと、行の右端にリンク付きのラベルが付きます（PR は #1234、GitLab のマージリクエストは !1234）。SSH や tmux でもリンクを出力するため、プレーンテキストにしたいときは FORCE_HYPERLINK=0 を設定します。複数の PR に結びついたときは 3 PRs のように件数が出ます（ピークパネルで全部見られる）。

PR で終わる作業は、番号が緑になったらレビューしてマージします。PR を見つけるしくみは次のとおりです。

• gh で PR の編集・コメント・クローズ・ready 化をしたときは、そのコマンドの出力が示す PR にリンクする（gh pr merge は対話端末にしか結果を出さないため、リンクされないことが多い）
• gh pr checkout やブランチへの push をしたときは、gh pr view でブランチの開いている PR を引いてリンクする
• push の時点で PR がなくても、同じディレクトリでのその後の git・gh・glab・curl の実行のうち最大5回まで、ブランチの検索を再試行する

ピークと返信#

選んだ行で Space を押すとピークパネルが開きます。行が端末の端で切る1文を、状態に応じて表示します。

• 入力待ちのセッション：聞いている質問そのもの（返信の入力欄の上）
• 完了したセッション：その結果
• 作業中のセッション：状態の全文

続けて結びついた PR が並びます。入力待ちなら waiting 3m のように待ち時間が出ます（行の右端の経過時間とは別で、こちらはセッション開始からの時間です）。

返信を入力して Enter で送ります。返信の頭に ! を付けると、Bash コマンドとして送ります。返信がどう扱われるかは、セッションの状態と送る内容で変わります。

• 作業中のセッション：返信は応答を中断せず、セッションのメッセージのキューに入り、キューに入れた入力が効くときに効く。コマンドは、セッション自身のプロンプトで打てばすぐ動くものでも、ターンが終わるまで待つ（v2.1.287 以降）
• ちょうど /stop という返信：セッションに届けず、すぐ止める（作業中でも入力待ちでも）
• シェルのジョブ（「シェルコマンドを動かす」の節）：/stop を含め、返信はコマンドの端末への入力として渡る

セッションが入力待ちのときの答え方は、待っているもので変わります。

• 選択肢つきの質問：パネルが選択肢を番号つきで並べる。返信欄が空のときに番号キーを押すと入力欄に入り、Enter で送る。自分の答えを打ってもよい
• 選択肢のない質問：答えを打つ。空の入力欄に提案された返信が出ているときは、Tab で入力欄に入れて、編集してから送れる
• 権限プロンプトや、ほかのダイアログ（サンドボックスのプロンプトや MCP サーバーの入力の要求など）：返信しても答えにならず、返信はキューで待つ。ダイアログに答えるには → でアタッチする。権限プロンプトは、実行したい内容がテキストで出る（番号の選択肢はない）
• PermissionRequest や PreToolUse フックの出力が検証できないときは、行に hook output invalid: と検証エラーが出る。ほかの失敗は「フックが失敗した」と出る。セッションは同じ要求で待ち続ける
• バックグラウンドサービスに届かないなどで送れなかった返信は保存され、プロセスが再び始まったときに次のプロンプトとして送られる（! 付きは保存されない）
• 音声入力を有効にしていれば、返信欄でも画面下の投入欄でも、プッシュトゥトークで話して入力できる

ピークを開いたまま ↑ ↓ で隣のセッションをのぞけ、→ でアタッチできます。

アタッチと切り離し#

行で Enter か → を押すとアタッチし、エージェントビューは完全な対話セッションに置き換わります。離れていた間の経緯を、Claude が短くまとめます。コマンドやキー操作は、通常のセッションと同じに使えます。

• アタッチしたセッションは、tui 設定にかかわらず常に全画面モードで描画される（端末のスクロールバックがないため）。PgUp・PgDn・マウスホイールでスクロールし、Ctrl+O でトランスクリプトモードにする
• 空のプロンプトで ←、または /exit で切り離して一覧へ戻る（claude attach <id> で開いたときも同じ）。/btw のオーバーレイが開いていても ← で切り離せる（v2.1.257 以降）。答え中の質問は続き、次のアタッチでオーバーレイが開き直る
• Windows では、アタッチの約0.5秒以内に ← を押すと Ambiguous ←, press again to detach と出る。もう一度押す
• Ctrl+Z も切り離す。アタッチ元（エージェントビューまたはシェル）へ戻る。ダイアログにフォーカスがあって ← が効かないときに使う
• Ctrl+C は通常どおり中断の動作（実行中の応答や ! のシェルコマンドを止める）。空のプロンプトで2回押すと切り離す
• 切り離してもセッションは止まらない（←・Ctrl+Z・/exit・Ctrl+C 2回・Ctrl+D 2回）。中から終わらせるには /stop

ターミナルを離れずにセッションを切り替える#

前面で動かしている（エージェントビューからアタッチしたものではない）セッションで、空のプロンプトの ← を押すと、そのセッションをバックグラウンドにして、その行を選んだエージェントビューを開きます。アタッチ中の同じ操作は切り離しです。

• 直前に入力を消した・履歴をたどったときは確認が入る（1回目で Press ← again to open agents、アタッチ中は Press ← again to go back to agents、2回目で切り替え）
• 切り替え後、一覧の上に Your conversation moved to the background と出る。Enter で会話を開き直し、Esc で切り替えを取り消して会話へ戻り（Still starting — try again in a moment と出たら少し待って再度押す）、Ctrl+C 2回でシェルへ抜ける
• 開き直せないときは、終了して claude --resume のコマンドを出力する
• Claude のタスクリストは会話といっしょにバックグラウンドへ移る
• 実行中のツールがあれば、最大約10秒終わりを待ってからバックグラウンドにする。もう一度 ← を押すと待たずに送る。前面のサブエージェントが動いている間は10秒の制限がなく待ち続け、Still backgrounding after the current tool と出る。待たずに送るとそのサブエージェントは最初からやり直しになる。ワークフローのサブエージェントは待たず、Background this session? ダイアログが出る
• 送信していない入力があるときはバックグラウンドにせず、Backgrounding cancelled — you have unsent text in the input. Send it or clear it, then press ← again. と出る
• 会話にメッセージがなくても行は作られるので、→ で戻れる
• 前面セッションでのこのショートカットは、/config の leftArrowOpensAgents で止められる

一覧を整理する#

入力待ちのものが上に来るよう、「Ready for review」と「Needs input」が「Working」と「Completed」の上に並びます。グループ名は上の状態と1対1ではありません。開いた PR があるセッションは「Ready for review」に、完了・失敗・停止は「Completed」にまとまります。

• Ctrl+S：ディレクトリごとのグルーピングに切り替える（選択は保持される）
• Ctrl+T：セッションを上に固定し、待機中もプロセスを動かし続ける
• Shift+↑ / Shift+↓：並べ替える
• Ctrl+R：名前を変える
• グループの見出しで Enter：折りたたむ（絞り込み中は、すべてのグループが開いたまま）
• Ctrl+X：セッションを止める。2秒以内にもう一度で削除する。グループの見出しで押すと、確認のあとにそのグループ全部を削除する。停止に失敗しても2回目で削除される。Esc で確認をやめる

削除すると、行は消えます。会話のトランスクリプトは常に手元に残り、claude --resume で開けます。worktree の扱いなど削除の詳細は、下の「削除で何が消えるか」を見てください。

v2.1.212 以降は、投入欄に /resume と入力すると、起動元のリポジトリの過去のセッション（削除したものを含む。すでに行があるものは除く）が新しい順に出ます。↑ ↓ で選び、Enter でバックグラウンドセッションとして再開し、Esc で閉じます。ピッカーが開くのは単独の /resume だけです。ID や検索語を付けた場合、--cwd で範囲を絞っている場合、--safe-mode で始めた場合、--permission-mode や --settings のようなフラグ付きで開いた場合は、attach to a session to run it と出ます。

画面に収まらない完了済みのセッションは … N more の行にたたまれます。失敗したものと PR が開いているものは常に見えます。背の低い端末では、ヘッダーが1行にまとまります。

絞り込み#

投入欄の先頭に次のどれかを入れると、入力につれて一覧が絞り込まれます。

絞り込みを組み合わせるには、a:・s:・n:・o: で始めて、スペースで区切って足します。すべてに合うセッションが出ます。たとえば s:blocked a:reviewer は、待ち状態の reviewer のセッションです。

絞り込みの間は、折りたたんだグループが開いて一致したものを見せ、一致の1つが選ばれるので、Enter で開けます。入力を消すと絞り込みが外れ、それらのグループはまた折りたたまれます。

キーボードショートカット#

エージェントビューで ? を押すと、文脈ごとの全ショートカットが出ます。

Agents コンテキストにアクションがあるショートカットは、keybindings.json に従います。Ctrl+G も、Chat コンテキストの chat:externalEditor で割り当て直せます。v2.1.288 以降は Ctrl+F・Alt+↑・Alt+↓ と Ctrl+R も割り当て直せます。

新しいエージェントを投入する#

投入欄、動いているセッション、シェルの3つの入口があります。

投入欄から#

画面下の入力欄にプロンプトを書いて Enter を押すと、新しいバックグラウンドセッションが始まります。名前はプロンプトから Haiku クラスのモデルが自動でつけ、Ctrl+R で変えられます。画像は貼り付けて添えられます。800 文字を超える、または3行を超える貼り付けは [Pasted text #N] に畳まれ（全文は送られる）、同じ内容をもう一度貼ると中身が展開されます。

プロンプトの頭や途中に書くものでセッションの始め方が変わります。

投入欄の中で動くコマンドは次のものだけです。

• /exit・/quit：エージェントビューを閉じる
• /logout：サインアウトする
• /model：投入するときのモデルを決める
• /login：セッションにアタッチせずに、サインインのダイアログを開く
• 単独の /resume（別名 /continue）：過去のセッションを選ぶピッカーを開く（v2.1.212 以降）

スキル・自作のコマンド・/init のようにプロンプトへ展開される組み込みコマンドは、新しいセッションの最初のプロンプトとして送られます。ほかの組み込みコマンドは attach to a session to run it と出て、打った内容は入力欄に残ります。同じ @name がサブエージェントと隣のリポジトリの両方に合うときは、サブエージェントが優先されます。最初の語がサブエージェント名に合う場合も同様です。はっきりさせたいときは @ の形を使うか、別の語で始めます。

別のディレクトリへ投入する#

新しいセッションは、エージェントビューを開いたディレクトリで動きます。別のディレクトリにするには次のいずれかです。

• そのディレクトリで claude agents を開く
• 親のディレクトリで開き、プロンプトで @<repo> と子のリポジトリを指す。@ を打つと、起動ディレクトリの1つ下の Git リポジトリ・起動元リポジトリのディレクトリ内にある登録済みの worktree（.claude/worktrees/ のようなもの。ブランチ名が付く。git worktree add ../feature のような外のものは出ない）・すでにセッションがあるディレクトリが候補に出る。名前に空白を含むディレクトリは出ない
• シェルで cd して claude --bg "<prompt>" を実行する

ディレクトリでグルーピングしているときは、選んだ行のディレクトリへ投入されます。

動いているセッションから#

/background（別名 /bg）は現在の会話をバックグラウンドへ移して端末を空けます。/fork は、コピーをバックグラウンドへ送り、手元の会話はそのまま続けます。

/bg で会話を移す#

/bg run the test suite and fix any failures のようにプロンプトを足せます。応答中に実行すると、応答はバックグラウンドで続きます。サブエージェント・バックグラウンドのシェルコマンド・ワークフロー・モニターが動いたままセッションを終えようとすると Background work is running ダイアログが出て、「Move to background and exit」で同じようにバックグラウンドへ移して終了できます（エージェントビューを無効にしていると、この選択肢は出ません）。同じ名前の行がすでにあれば、新しい行は my-session (2) のように番号が付きます。

/fork で会話をコピーする#

現在の会話を、新しいバックグラウンドセッションにコピーします。元の会話はそのまま動きます。コピーは、そこまでの会話・モデル・権限モード・effort・セッション中に足したディレクトリや「今後は確認しない」の許可を引き継ぎ、独立した行として出ます。以後の2つの会話は独立で、セッション間のメッセージが有効なら、互いに明示的にメッセージを送れます。

• v2.1.212 以降の機能。v2.1.161〜v2.1.211 の /fork はフォークしたサブエージェントを始める動作で、それは今 /subtask になっている。エージェントビューを無効にしていると /fork はサブエージェントのフォークのままで、/subtask は使えない
• /fork open a draft pull request with the work so far のようにプロンプトを付けると、すぐ作業を始める。付けないと最初の指示を待ち、行を選んで Space を押すか claude attach <id> で送る（行に space to send it a prompt と出る）
• 確認の1行に、コピーの状態（session running など）・行の名前・claude attach 用のセッション ID が出る。名前をクリックするとコピーへ切り替わる
• コピーも投入されたセッションと同様、ファイルを編集する前に自分用の worktree へ移ります（下の「worktree と編集の分離」）。その場で編集する設定のときは例外
• git リポジトリの外では、フックで作った worktree から移したコピーだけが指示を受ける。WorktreeCreate フックがなければその場で編集する。あなたの worktree から移したコピーは、その worktree を編集・実行・出入りしないよう指示される
• あなたのセッションが開始後に worktree へ移っていた場合、コピーは移る前の場所から始まり、独自の worktree でコード変更をする。ブランチにいるなら、あなたの作業の上に積む作業のときは、そのブランチを土台にするよう指示される。確認の行は runs in the origin tree で終わる
• リンクされた worktree で起動し、メインの作業ツリーがあるリポジトリなら、コピーはメインの作業ツリーで始まる（確認の行は runs in the origin tree）
• bare リポジトリ構成の worktree で起動したときは戻る先がないので、コピーはその場に残り、確認の行は edits this checkout で終わる。worktree の隔離が無効なときも同じ
• 置き換えたシステムプロンプトや --tools の許可リストなど、コピーが引き継げない起動フラグで始めたセッションはフォークできない。エージェントビューから投入したセッションは普通にフォークできる

バックグラウンドへ移すと何が引き継がれるか#

バックグラウンドへ移すと、保存された会話から再開する新しいプロセスが始まり、進行中の作業が移ります。バックグラウンドのシェルコマンド・バックグラウンドのサブエージェント・ワークフロー・/loop で作ったスケジュール・成果物（artifact）のコメントへの自動返信は、移って動き続けます。サブエージェントは、自分が始めたものすべてといっしょに移るので、移れるのはそのすべてが移せるときだけです。

• ワークフローのサブエージェントがまだ動いていると、Background this session? ダイアログが何個やり直しになるかを出して確認します。「Stay」で終わるまで待てます。確認すると、動いていたサブエージェントは最初からやり直しになり、それまでのトークンは再び使われます
• 実行中のモニターのように移せない作業は止められます（それを所有するバックグラウンドのサブエージェントも）。そうした作業があるときも Background this session? ダイアログが出ます
• 移ったあとは、新しいサブエージェント・モニター・バックグラウンドコマンドを始められ、切り離して再アタッチしても続く
• 進行中の作業を移さずに止めたいときは、環境変数 CLAUDE_DISABLE_ADOPT=1 を設定する。バックグラウンドへ移す前に確認が出る

起動時の設定フラグは、移ったセッションにも引き継がれます。

• --mcp-config と --strict-mcp-config
• --settings
• --setting-sources
• --add-dir
• --plugin-dir
• --fallback-model
• --allow-dangerously-skip-permissions

セッション中に /add-dir で足したディレクトリも引き継がれます。--allow-dangerously-skip-permissions を引き継ぐと bypassPermissions に切り替えられる状態が保たれますが、何かが新しく許可されるわけではなく、モードには1回きりの対話での承認が要ります。

シェルから#

--bg（長い形は --background）を付けると、そのままバックグラウンドで始まります。

claude --bg "investigate the flaky SettingsChangeDetector test"

• プロンプトは位置引数で、-p の値ではない。-p や --print と組み合わせると、セッションを作る前に拒否される
• 信頼していないディレクトリでは、先にワークスペースの信頼ダイアログが出る（断ると終了）。ダイアログが出せないスクリプトなどでは Workspace not trusted エラーで終わる
• 自分で定義したサブエージェントをメインのエージェントとして動かすには --agent と組み合わせる。名前が合わないと no agent named の警告のあと、セッションは --agent '<name>' not found のエラーですぐ終わる（それでもバックグラウンドにしたと表示される）
• 再開・再起動時はエージェントとそのツール制限が復元される。エージェントはまずセッション自身のディレクトリ（信頼済みの場合）から探すので、プロジェクト単位のエージェントも別のディレクトリからの再開で読み込まれる

claude --agent code-reviewer --bg "address review comments on PR 1234"
claude --resume 1f0e2c9a-6d0b-4c11-9f39-2a77c1d4e8b5 --bg "pick up where you left off and finish the migration"
claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

既存の会話をバックグラウンドで続けるには、完全なセッション ID を --resume で渡します。v2.1.257 以降は、同じ ID のまま続けるか、新しい ID でコピーを始めて理由を note: の行に出します。同じ ID で続けたときは、claude agents に1行だけ出ます。--continue・名前やファイルパスつきの --resume・値なしの --resume と組み合わせると常にコピーになります。注意書きなしでコピーを作るには --fork-session を足します。--name で、自動の名前の代わりに表示名を決められます。

投入後は、短い ID と管理コマンドが出力されます。バックグラウンドサービスが動いていなければ、先に Starting background service… が出ることがあります。

backgrounded · 7c5dcf5d · flaky-test-fix
  claude agents             list sessions
  claude attach 7c5dcf5d    open in this terminal
  claude logs 7c5dcf5d      show recent output
  claude stop 7c5dcf5d      stop this session

シェルコマンドを動かす#

Claude のセッションではなくシェルコマンドをバックグラウンドのジョブとして動かすには --exec を使います。投入欄の最初の文字を ! にしても同じです。

claude --bg --exec 'pytest -x'

PTY つきのジョブとして動き、最新の出力の1行が状態として出る行になります。モデルは呼ばれず、出力はどのセッションにも送られません。出力は、アタッチ・Space のピーク・claude logs <id> で見られます。出力はメモリ上にだけあり、ディスクには書かれません。行と出力は、コマンドの終了から約5分後に自動で片づくので、その前に読んでください。

worktree と編集の分離#

エージェントビューから投入したバックグラウンドセッションと、claude --bg で始めたものは、まず作業ディレクトリで始まります。ファイルを編集する前に、Claude が .claude/worktrees/ 以下の隔離された git worktree にセッションを移します。並列のセッションは同じチェックアウトを読めても、書くのはそれぞれ自分の worktree です。worktree に入ったあとは、そのセッションと起こしたサブエージェントに worktree の隔離が強制されます。

次の場合は worktree を作りません。

• すでにリンクされた git worktree の中にいる（Claude が作ったものでも、git worktree add で別の場所に作ったものでも）
• 編集するファイルが、リンクされた git worktree の中にある
• 作業ディレクトリが git リポジトリではなく、WorktreeCreate フックも設定されていない
• 書き込みが作業ディレクトリの外にある
• すでに開いていたセッションを ← か /background でバックグラウンドへ移した（そのセッションは、それまで作業していた場所で編集を続ける）

git の worktree が現実的でないリポジトリでは、プロジェクトの .claude/settings.json で隔離を切れます。このときバックグラウンドセッションは、作業コピーを直接編集します。

{
  "worktree": {
    "bgIsolation": "none"
  }
}

git リポジトリでない場所では、セッションは作業ディレクトリへ直接書き、互いに隔離されません。同じファイルを編集する並列のセッションを投入しないでください。ほかのバージョン管理を使うなら、WorktreeCreate フックを設定すれば git と同じように隔離されます。フックが git リポジトリでない場所で失敗したときは、隔離を飛ばしてその場で編集します。git リポジトリの中では、編集の前に Claude が worktree へ移すセッションは、その移動が済むまで共有チェックアウトのファイルを編集できません。

セッションの worktree のパスは、ピークするか、アタッチして作業ディレクトリを見れば分かります。バックグラウンドセッションが起こしたサブエージェントは、セッションの作業ディレクトリを引き継ぐので、セッションが worktree に入ったあとは、サブエージェントの編集がその worktree に入ります。サブエージェントに別の worktree を持たせるには、frontmatter に isolation: worktree を書くか、起動時に isolation: "worktree" を渡します。

worktree でコードを変えたバックグラウンドセッションには、終える前に成果を残すよう指示が出ます。

• コミットして push する：確認なしでコミットし、リモートがあればブランチを push する
• ドラフトの PR：作業が求めるなら開く。行に #N のラベルが出る
• しないこと：main や master への push・強制 push・マージ
• 作業・CLAUDE.md・メモリに、コミットや push は自分でやると書いてあれば、git は任せる

自分で隔離していないチェックアウトを編集するセッションは、コミットやブランチの切り替えの前に確認します（隔離が "none" のとき、worktree への移動に失敗したとき、すでにあった worktree の中で始まったとき）。どの作業も、終わりに、何をしたか・成果がどこにあるか（パス・ブランチ・PR・答えそのもの）を報告して終わります。

削除で何が消えるか#

Ctrl+X を2回（エージェントビュー）か claude rm で削除します。例外を除き、セッションは一覧から消え、トランスクリプトは手元に残って claude --resume で開けます。Claude が作った worktree の扱いは次のとおりです。

• エージェントビューは、未コミットの変更も含めて消す。残したいものは先にコミットする
• claude rm は、未コミットの変更があれば worktree もセッションの行も残す
• 別の実行中のセッションが使っている、またはロックされている worktree は、どちらも消さない。worktree とセッションを残し、理由とディレクトリを示す（エージェントビューの行には not deleted）。相手を閉じてからもう一度削除する
• worktree に、ほかに保存されていると確認できないコミットがあるときは、worktree とセッションを残し、ブランチ名と未 push のコミット数を示す。コミットを push する（またはリモートの既定ブランチのローカルコピーにマージし、そのブランチをメインのチェックアウトに出しておく）と削除でき、リモートにあるコミットなどは邪魔にならない。捨てるなら、エージェントビューで Ctrl+X を2回、または表示された claude rm <id> --discard-unpushed を実行すると、ブランチ・コミット・未コミットの変更ごと消える。もう一度削除したときに捨てるのは、拒否の時点で示したものだけで、その後にコミットが増えていれば再び残して最新の状態を示す。ほかの終わったセッションの記録も同じ worktree を指していれば、それも残る
• git worktree prune などで git が認識しなくなった worktree は、削除を邪魔しない。セッションを消し、ディレクトリはディスクに残す
• git や WorktreeRemove フックが worktree を消せなかったときは、worktree とセッションを残し、原因（フックなら exited 1 のような終わり方と stderr の先頭）を示す。次のいずれかで進む：もう一度削除してディレクトリを強制的に消す（claude rm <id> --force-remove-worktree <worktree-id>。ブランチはリポジトリに残る）／邪魔なものを直す（コミットや stash・別の Git リポジトリの移動・ディレクトリを使っているものを閉じる・フックの修正）してから削除し直す／自分でディレクトリを消してから削除し直す
• 強制削除が示されるのは、次のすべてを確認できたときだけ：.claude/worktrees/ 以下のリポジトリのリンクされた worktree である／worktree にも、チェックアウト済みのサブモジュールにも、追跡ファイルの未コミットの変更がない／ほかのセッションの記録が指していない。サブモジュールの状態が確認できない（別の Git リポジトリで置き換えられているなど）ときも、示されない
• 自分で作り、その中でセッションを始めた worktree は、どちらの方法でも残る
• worktree のディレクトリがどの git リポジトリにも属さない（リポジトリを消した・WorktreeCreate フックが別の場所に作った）セッションも、削除できる。ファイルが残っているあいだ、エージェントビューは同じ Ctrl+X 2回の確認のあとに捨てる（フックで作ったディレクトリでは WorktreeRemove フックを動かす。フックがなければ削除を拒否してセッションを残す）。claude rm はセッションと worktree を残し、理由を示す。どちらも、ほかの終わったセッションの記録が指すディレクトリは残す

モデル・権限モード・effort#

バックグラウンドセッションは、どこから・どうやって投入されたかで、設定・プロバイダー・権限モード・モデル・effort が決まります。

投入時のモデル#

エージェントビューのヘッダーに出るモデル名が、投入の既定です。ユーザー設定の model から来ます。/model ピッカーで選ぶか、設定を直接編集して変えます。エージェントビューを開くときに --model を渡すと、その実行のあいだ上書きされます。

エージェントビューの中では、投入欄に /model <name> と入れて Enter を押すと、ヘッダーに (session) の印つきでそのモデルが出て、以後の投入に使われます。/model default で上書きをやめます。上書きは、その claude agents の実行中だけ続き、設定ファイルには書かれません。

/model opus
refactor auth
/model sonnet
run the test suite

1つのセッションだけモデルを変えるには、次のいずれかです。

• シェルから claude --bg に --model を渡す
• 動いているセッションにアタッチして /model を実行する。ピッカーで選ぶか /model <name> と打つと、新しいセッションの既定として保存される。ピッカーで s を押すとそのセッションだけの切り替えになり、これは再起動しても残る
• frontmatter に model を書いたサブエージェントを投入する

設定とプロバイダー#

バックグラウンドセッションは、動くディレクトリの設定を読みます。プロジェクト設定の env の値（ANTHROPIC_MODEL やプロバイダーの変数）は、そのディレクトリのバックグラウンドセッション全部に効きます。投入元のシェルの PATH、クラウドプロバイダーの選択（CLAUDE_CODE_USE_BEDROCK・CLAUDE_CODE_USE_VERTEX など）、ANTHROPIC_DEFAULT_*_MODEL の別名、そこでエクスポートした CLAUDE_CODE_EXTRA_BODY の上書きも引き継ぎます。

LLM ゲートウェイ#

LLM ゲートウェイを通すときは、ゲートウェイの変数をシェルでエクスポートせず、設定ファイルの env に置きます。バックグラウンドセッションは、ほかの設定といっしょに読みます。

ゲートウェイの ANTHROPIC_BASE_URL をシェルでだけエクスポートした場合、ANTHROPIC_CUSTOM_HEADERS や資格情報と合わせて届くのは、スーパーバイザー自身が同じゲートウェイをエクスポートしたシェルから起動されていて、かつ次のときだけです。

• ← や /background で自分のセッションをバックグラウンドにする
• いまいるディレクトリに投入する
• いまいるディレクトリの止まったセッションに、アタッチか返信で起こす

クラウドプロバイダーの前に置くゲートウェイも転送されます。シェルがプロバイダーを選び、エンドポイントと認証省略のフラグをエクスポートしていれば、そのペアが ANTHROPIC_BASE_URL と同じ条件で転送されます（例：CLAUDE_CODE_USE_VERTEX=1 と ANTHROPIC_VERTEX_BASE_URL と CLAUDE_CODE_SKIP_VERTEX_AUTH=1）。転送されたゲートウェイは、そのセッションの実行中のプロセスにだけ効き、ディスクには書かれません。

権限モード#

権限モードは、セッションの始め方で決まります。

• /bg や ← でバックグラウンドにした：そのときの権限モードを保つ（acceptEdits や auto に切り替えていれば、そのまま）
• ← で開いたエージェントビューから投入した：投入先の自分の設定が先で、ほかに決まらなければ、元のセッションの権限モードが使われる
• シェルで開いた claude agents や claude --bg から投入した：そのディレクトリで新しい claude セッションを始めたときと同じ（投入の既定つきで開いた場合を除く）

← で開いたビューから投入するときは、次の順で最初に当てはまるものから権限モードを取ります。

1. 投入先ディレクトリの permissions.defaultMode。auto と bypassPermissions は、管理設定・--settings のファイル・~/.claude/settings.json からだけ有効。プロジェクトの .claude/settings.json や .claude/settings.local.json の defaultMode が、元のセッションより許可の広いモードなら拒否される
2. 元のセッションの権限モード

拒否されたときは、一覧の次のものが決めます。たとえば plan モードのセッションから、チェックイン済みの設定が acceptEdits のディレクトリへ投入すると、plan モードで始まります。その defaultMode を ~/.claude/settings.json に移せば、元のモードに関係なく効きます。許可の広さは、plan、次に Manual と dontAsk、次に acceptEdits と auto（互いに他方より広いと数える）、最後に bypassPermissions の順です。

投入の既定#

エージェントビューから投入するすべてのセッションの既定は、開くときに次のフラグで渡します。

claude agents --permission-mode plan --model opus --effort high

有効な既定は、投入欄の下のフッターに出ます。claude --bg --permission-mode bypassPermissions は、claude --dangerously-skip-permissions を対話で1回実行して免責事項を承認するまで拒否されます。claude agents にこの2つのフラグを渡したときも、未承認なら同じ免責事項が出て、承認すると、そのビューから始めるセッションに bypassPermissions が適用されます。

再起動をまたいで残るもの#

バックグラウンドセッションの権限モード・モデル・effort と、引き継いだ設定フラグは、スーパーバイザーがプロセスを止めて再起動しても残ります。claude --bg --dangerously-skip-permissions で始めたセッションは再起動後も bypassPermissions のままで、途中で /model や /effort で変えたものも残ります。

effort を --effort や /effort でなく設定から取っているセッションは、プロセスを始めるたびに設定を読み直します。settings.json の保存された effort（effortLevel キーか modelSettings の項目）を直すと、← や /bg でバックグラウンドにしたセッションと、その後の再起動に反映されます。/rename や Ctrl+R でつけた名前も再起動後に残り、claude --resume <name> で開けます。アタッチ中に Ctrl+S で退避したプロンプトも、セッションとともに残ります（貼り付けた内容は残りません）。

設定・プラグイン・MCP サーバー#

エージェントビューは、設定・プラグイン・MCP サーバー・追加ディレクトリについて claude と同じフラグを受け取り、投入するセッションにも渡します。--settings・--setting-sources・--plugin-dir は、エージェントビュー自身にも適用されます。

--add-dir・--plugin-dir・--mcp-config は値ごとに繰り返します（--add-dir a b c のような空白区切りは不可）。--settings・--setting-sources・--plugin-dir は agents の前でも後でも置けますが、--add-dir と --mcp-config は agents の後に置いてください。前に置くと claude agents --json が unknown option エラーで失敗します。--settings は存在するファイルを指す必要があり、なければ Settings file not found で終了します。

claude agents --settings ./ci-settings.json --add-dir ../shared-lib

シェルからセッションを管理する#

バックグラウンドセッションにはそれぞれ短い ID があります。claude --bg で表示され、~/.claude/jobs/ の下のディレクトリ名でもあります。

JSON で一覧する#

claude agents --json は、生きているセッション全部と、プロセスが終了していても作業中か待ち状態のバックグラウンドセッションを、JSON の配列で出して終了します。--all で完了済みのバックグラウンドセッションも含め、--cwd <path> でそのディレクトリ以下に絞ります。

スクリプトから状態を読む#

状態を Claude Code の外（ステータスバー・スケジューラー・バックグラウンド作業を見守る別の Claude セッションなど）から読む正式な方法は claude agents --json です。プロセスが終了したセッションも残る claude agents --json --all を定期的に引き、各項目の state・status・waitingFor を読みます。

ターンを終えて次の指示を待つセッションは blocked ではなく done です。blocked は、続けるためにあなたの何かが要る状態だけを指します。

バックグラウンドセッションのしくみ#

エージェントビューに並ぶセッションは、いまアタッチしているかにかかわらず、すべてバックグラウンドセッションです。claude を直接実行して始めたセッションは、その端末に結びつき、閉じると終わります（バックグラウンドへ送った場合を除く）。どちらかは /status の Session kind の行で分かります（バックグラウンドなら background job · attached か background job · unattended、それ以外は interactive）。

スーパーバイザー#

スーパーバイザーは、エージェントビューや端末を閉じてもセッションが動き続けるよう、セッションを動かすバックグラウンドサービスです。初めてバックグラウンドにするか、エージェントビューを開いたときに始まり、自分で管理する必要はありません。各セッションはスーパーバイザーの下の独立した Claude Code プロセスで、状態によって次のように扱われます。

• 作業中・権限プロンプトなどのダイアログで停止中・アタッチ中：プロセスは動き続ける（動いているサブエージェント・ワークフロー・モニターは作業中と数える）
• 終了済み、または次のメッセージ待ちで、約1時間アタッチされていない：リソースを空けるためプロセスを止める（質問して終えたターンも、次のメッセージ待ち）。会話はディスクに残り、次のアタッチや返信で続きから再開する。Ctrl+T で固定すると動かし続けられる
• スーパーバイザーが動いているのにプロセスが予期せず終了した：スーパーバイザーが再起動する。← や /background で自分でバックグラウンドにしたセッションを kill などで終えると、再起動せず停止扱いになる
• 自動更新のあと：スーパーバイザーは新しいバージョンで自分を再起動し、アイドルのセッションをバックグラウンドで移す。作業中・入力待ち・アタッチ中のセッションは中断されない

セッションのプロセスが止まる・再起動するとき、そこで始めたバックグラウンドのシェルコマンド・ワークフロー・バックグラウンドのサブエージェントは次のプロセスへ移ります。動いているモニターと、サブエージェントが始めたシェルコマンドは、プロセスとともに止まります。セッションを削除すると、移っていたものすべてが止まります。プロセスとともに止めたいときは、環境変数 CLAUDE_CODE_DISABLE_BG_EXIT_HANDOFF を 1 にします。スーパーバイザーとセッションは、対話セッションと同じ保存済みの資格情報で認証します。

状態の保存場所#

状態は、Claude Code の設定ディレクトリの下にあります。CLAUDE_CONFIG_DIR を設定すると、スーパーバイザーは ~/.claude の代わりにそのディレクトリを使い、独立したインスタンスとして別のセッションを持ちます。

各バックグラウンドセッションには、環境変数 CLAUDE_JOB_DIR（~/.claude/jobs/<id>）が設定されます。セッションが動かすシェルコマンドは、$CLAUDE_JOB_DIR/tmp に一時ファイルを書けば、並列のセッションとぶつかりません。claude daemon status で、スーパーバイザーに届くか・プロセス ID とバージョン・ソケットのディレクトリ・生きているバックグラウンドセッション数を確認できます。動いているスーパーバイザーが、呼び出した claude と別のバージョンのとき（更新後、スーパーバイザーがまだ再起動していないとき）は警告が出て、claude daemon stop --any を案内します（OS のサービスとして入れているときは、フラグなしの claude daemon stop）。古いバージョンの Claude Code が state.json や roster.json を更新しても、知らないフィールドは保たれ、新しいバージョンのセッションにも届き続けます。

エージェントビューを無効にする#

バックグラウンドエージェントとエージェントビューを完全に止めるには、disableAgentView 設定を true にするか、環境変数 CLAUDE_CODE_DISABLE_AGENT_VIEW を設定します。管理者は管理設定で強制できます。

困ったとき#

シャットダウン後に failed や stopped になる#

マシンのシャットダウンや再起動で、実行中のバックグラウンドセッションは止まります。入力待ちだったセッションは、戻ったときも「Needs input」に残ります。ほかの実行中のセッションは、最後に進んだ時刻からの時間で表示が変わります。

• 48時間以内：failed と表示される。アタッチか返信をすると、続きから再開する
• 48時間を超えた（数日間マシンが切れていたときなど）：ended while the background service was off つきの stopped と表示される。行で Enter を押すと、フッターに Press enter again to resume this session (it ended while the background service was off), or ctrl+x to delete it. と出る。同じ行でもう一度 Enter を押すと保存された会話を再開する。返信や claude attach <id> なら、このフッターなしで再開する

トランスクリプトの掃除（cleanupPeriodDays）で止まったセッションの保存された会話が消えていると、行は開けず、再開するものがないと表示されます。claude rm <id> で行を消せます（上の残る場合を除く）。claude respawn <id> なら元のプロンプトをもう一度実行します。スリープだけではセッションは止まらず、復帰時にスーパーバイザーが再接続します。

会話がすでに開かれていると出る#

2つのプロセスが同じトランスクリプトに書くことはできません。止まったセッションの保存された会話が、別の生きている Claude Code プロセスで開かれていると、セッション自身のプロセスの起動は拒否されます。

• 会話を claude --resume や /resume で再開したターミナルがある：行に Open in a terminal と出て、開こうとすると Can't open — this session is running in another terminal。そのターミナルで続けるか、終了してから行を開き直す
• ほかの非対話の Claude Code プロセス（終了していない、同じ会話のバックグラウンドセッションのプロセスなど）がある：This conversation is already open in another running Claude session と出る。そのプロセスを使うか、終了を待って開き直す

拒否された試行で入力した返信は保存され、次にセッションが始まるときに送られます。

バックグラウンドサービスが応答しない#

アタッチ・ピーク・claude logs で「バックグラウンドサービスが応答しない」と出るのは、スーパーバイザーが止まっている可能性が高いときです。止めて、次の claude agents で新しく始めます。再起動をまたいでバックグラウンドセッションを動かしたままにするには --keep-workers を付けます。

claude daemon stop --any --keep-workers

新しいスーパーバイザーが、動いているセッションに再接続します。--keep-workers がないと、セッションも終わります。--any は、インストール済みのサービスではなくオンデマンドで始まったスーパーバイザー（既定）を止める確認です。接続を受けられないまま起動したスーパーバイザーは、自分で終了してロックを手放します。コマンドが、記録されたプロセスをスーパーバイザーと確認できないと言って終わったときは、出力されたプロセス ID を確かめ、自分のスーパーバイザーなら自分で止めてから ~/.claude/daemon.lock を消します。Windows で停止の要求に応答しないときは、プロセス ID が出るので taskkill /PID <pid> で終わらせます（--keep-workers を付けていれば、バックグラウンドセッションは保たれます）。

制限#

• レート制限が効く：バックグラウンドセッションは、対話セッションと同じようにサブスクリプションの使用量を消費する。10個を並列で動かすと、1個のときの約10倍の速さで使い切る
• セッションはローカル：手元のマシンで動き、スリープでは保たれ、シャットダウンで止まる
• Claude が作った worktree は、エージェントビューでセッションを削除すると消える。コミットしてから削除する（削除が worktree を残す場合もある）

関連：Claude Code を Web で使うことで、マネージドなクラウド環境でセッションを動かせます。セッション間で調査結果を渡すにはセッション間のメッセージ、メッセージを送り合う複数のセッションをまとめるにはエージェントチームを使います。