背景

この連載では、Claude Codeの公式ドキュメントを1ページずつ読み解いていきます。公式ドキュメントは情報が網羅されている分、「結局どの機能を、どんな場面で使えばいいのか」は自分で考える必要があり、読むのに意外と時間がかかります。そこで、私が実務で使うために読み込んだ内容を「使う場面→実例コード」の順に整理して残していくことにしました。専門家の解説というより、一次情報を読んだ記録です。推測や動作を確認していない部分には、その都度そう書きます。

1. 一言でいうと何か

このページは、claude agents で開く「すべてのバックグラウンドセッションの一枚の画面」——エージェントビューの操作と仕組みを、端から端まで説明したものです。

前回（第64回）の並列化アプローチ比較で、エージェントビューは「独立したタスクを引き継いで、一目で状態を確認し、必要なときだけ介入する」枠に位置づけられていました。今回はその中身です。

冒頭の説明が本質を一文で言い切っています。実行中のもの、入力が必要なもの、完了したものが表示される。新しいセッションをディスパッチし、トランスクリプトをスクロールする代わりに一目でセッションの状態を確認し、セッションが必要とするときだけ介入する。

そして、これを成立させている前提が明記されています。各バックグラウンドセッションは完全な Claude Code の会話であり、ターミナルが接続されていなくてもバックグラウンドで実行し続ける——だから「いつでも開いて、返信して、去ることができる」。ここが claude を普通に起動したセッションとの決定的な違いです。claude を直接実行して開始されたセッションはそのターミナルに結び付けられ、ターミナルが閉じると終了します。

ページが扱う範囲は5つに整理されています。クイックスタート／エージェントビューでの監視／新しいエージェントのディスパッチ／シェルからのセッション管理／バックグラウンドセッションがどのようにホストされるか。最後の1つ——スーパーバイザープロセス——が、この機能全体を裏で支えている存在です。

大前提を先に置きます。エージェントビューはリサーチプレビューであり、Claude Code v2.1.139 以降が必要です。claude --version でバージョンを確認します。原文はさらに「インターフェースとキーボードショートカットは機能の進化に伴って変更される可能性があります」と明言しており、実際にこのページの末尾には v2.1.139 から v2.1.208 までの長大なバージョン履歴表が付いています。本記事はその履歴表を全部は引きません（後述）。

2. どういう場面で役立つか

シーン1：3つのタスクを投げて、別の作業に戻る

原文の例がそのまま使えます。バグ修正、プルリクエストレビュー、不安定なテストの調査を3つの行としてディスパッチし、別のウィンドウで作業を続け、行が入力が必要であることを示すか、結果が得られたときに確認します。

「毎ステップを監視することなく Claude が作業できる」タスクが複数あるときが、この機能の本領です。逆に言えば、一歩ごとにあなたの判断が要る作業には向きません。

シーン2：claude の代わりのエントリーポイントにする

原文はもう一歩踏み込んだ使い方を提案しています。**claude agents を claude の代わりにプライマリエントリーポイントとして使用できます。**エージェントビューからすべてのタスクをディスパッチし、フル会話が必要な場合はアタッチし、← を押してテーブルに戻る。

つまり「会話が主・一覧が従」ではなく「一覧が主・会話が従」に反転させる運用です。これは好みが分かれるところですが、常時3つ以上のセッションを回す人には合理的だと思います（これは筆者の評価であり、原文の主張ではありません）。

シーン3：結果をプルリクエストで受け取る

**セッションがプルリクエストを開くと、#1234 ラベルが行の右端に表示され、ハイパーリンクをサポートするターミナルではプルリクエストにリンクされます。**そして原文は運用の勘所をはっきり書いています。ほとんどのタスクでは、この列が結果を収集する場所です。プルリクエスト番号が緑になったときにプルリクエストをレビューしてマージします。

トランスクリプトを読みに行くのではなく、PR 番号の色を見る。これが想定されている完了確認の形です。

不要・向かないケース

• **クォータに余裕がない。**制限事項の筆頭がこれです。バックグラウンドセッションはインタラクティブセッションと同じようにサブスクリプション使用量を消費するため、10 個のエージェントを並行して実行するとクォータが 10 倍速く消費されます。
• マシンを落とす予定がある。****セッションはローカルで、**マシンがシャットダウンすると停止します。**スリープは大丈夫ですが、シャットダウンは駄目です。クラウドで動かしたいなら Claude Code on the web が案内されています。
• **同じファイルを触る並列タスクを、git リポジトリの外で回したい。**後述のワークツリー分離が効かないため、原文は明確に「同じファイルを編集する並列セッションのディスパッチを避けます」と書いています。
• **1つのセッションに追加指示を送りたいだけ。ディスパッチ入力はそういう場所ではありません。「ここで入力するすべてのプロンプトは独自の新しいセッションを開始します。」**フォローアップを送りたいならピークパネルで返信するか、アタッチします。
• **エージェント同士を会話させたい。**それはエージェントチームの領分です。Subagents と teammates はセッションが生成しても個別の行としてリストされません。
• 組織として無効化したい場合。****disableAgentView 設定を true にするか、CLAUDE_CODE_DISABLE_AGENT_VIEW 環境変数を設定します。管理者はマネージド設定を通じてこれを強制できます。

3. コマンドの実例と解説

このページはコード例が豊富です。フェンス付きコードブロックは全部で14種類あり、本記事ではそのすべてを原文どおり引用します。一方でバージョン履歴表（v2.1.139〜v2.1.208 の16行）とトラブルシューティングの10節は分量が大きいため、要点のみに絞ります。

前提の再掲：v2.1.139 以降が必要。各セッションはサブスクリプションクォータを独立して使用します。bypassPermissions 系のフラグは後述の1回限りの受け入れが必要です。

起動する

claude agents

エージェントビューが開き、下部に入力フィールドが表示され、セッションが開始されるとテーブルが埋まります。いつでも Esc を押してシェルに戻ります。セッションは離れている間も実行し続け、次にエージェントビューを開いたときに再度表示されます。

デフォルトの表示範囲は広めです。**リストはすべてのプロジェクト全体で開始したすべてのバックグラウンドセッションを表示します。**エージェントビューを開いたディレクトリは関係ありません。1プロジェクトに絞るなら --cwd を渡します。

claude agents --cwd ~/projects/my-app

これはそのディレクトリの下で開始されたセッションのみを表示します。なお ~/projects/my-app/.claude/worktrees/ の下のワークツリーに移動したセッションは、~/projects/my-app に属するものとしてカウントされます。

画面の読み方

一覧のサンプルが原文に載っています。

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
  ✢ playtest level 3          run 12 · all checkpoints cleared           in 4m
Completed
  ✻ title screen              result: menu, options, and credits done       9m
  ∙ sound effects             result: 14 SFX exported to assets/audio       4h
  … 6 more

各行はセッションの名前、現在のアクティビティ、およびセッションが作成されてからの経過時間を表示します。完了したセッションの経過時間は、実行にかかった時間で固定されます。

ここで重要なのは、アイコンが2つの情報を同時に運んでいることです。色とアニメーションがセッションの状態を示し、形状が基盤となるプロセスが実行しているかどうかを示します。

状態（色・アニメーション）：

状態	アイコン表示	意味
作業中	アニメーション	Claude がアクティブにツールを実行しているか、応答を生成しています
入力が必要	黄色	Claude は特定の質問または許可決定をあなたから待機しています
アイドル	薄い	セッションはすることがなく、次のプロンプトの準備ができています
完了	緑	タスクが正常に完了しました
失敗	赤	タスクがエラーで終了しました
停止	グレー	セッションは Ctrl+X または claude stop で停止されました

プロセスの生死（形状）：

形状	意味
✻ またはアニメーション ✽	セッションプロセスは生きており、すぐに返信します
∙	プロセスは終了しました。ピーク表示、返信、またはアタッチはできます。Claude は中断したところから再開します
✢	/loop セッションはイテレーション間でスリープしています。行は実行回数とカウントダウンを表示します

∙ が「死んでいる」ではなく「いつでも起こせる」を意味するのがポイントです。プロセスは止まっていても会話は生きています。

行の右の #N は**プルリクエストのラベルであり、状態アイコンの一部ではありません。**PR 番号の色は次のとおり。

カラー	プルリクエストステータス
黄色	チェックまたはレビューを待機中、またはチェックが失敗
緑	チェックが成功し、レビューがブロックされていない
紫	マージ済み
グレー	ドラフトまたはクローズ

セッションが複数のプルリクエストにリンクされている場合、ラベルはカウントを表示します。例えば 3 PRs のようになり、最も注意が必要なオープンプルリクエストで色付けされます。

なお、グループ名と状態は1対1ではありません。セッションはオープンなプルリクエストを持つときに Ready for review に移動し、Completed は完了、失敗、および停止したセッションを一緒に収集します。

行の1行要約は誰が書いているか

見落としやすいが実務上重要な点です。各行の1行の概要は Haiku クラスモデルによって生成されます。そしてターン終了時の概要と各ミッドターン書き直しは、通常のプロバイダーを通じた1つの短い Haiku クラスリクエストであり、セッション自体と同じデータ使用条件の下で請求および処理されます。

つまり行の文字が更新されるたびにモデルが呼ばれているわけではないが、呼ばれるときは課金対象です。頻度は制御されています。セッションがアクティブに作業している間、行テキストはセッション自身の最近の出力から最大15秒ごとに1回更新され、モデルリクエストを送信せず、モデルによる書き直しは約1分ごと、各書き直しの後に2倍待機して最大4分まで。

サードパーティプロバイダーでは注意が要ります。**Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、カスタムゲートウェイなどでは、Haiku モデルが設定されていない場合、リクエストはセッションのメインモデルにフォールバックします。**モデルを指定するには ANTHROPIC_DEFAULT_HAIKU_MODEL を設定します。メインモデルが Opus 級だと、行の要約をそのモデルで書くことになる——これはコスト面で無視できない差だと思います（原文はフォールバックの事実を述べるにとどまっています）。

ピークして返信する、アタッチする

**選択した行で Space を押してピークパネルを開きます。**開いたときに最初に出るものが状態で変わります。あなたを待機しているセッションは尋ねている正確な質問、完了したセッションはその結果、作業中のセッションはその完全なステータス文。

ほとんどの場合、ピークパネルで十分であり、フルトランスクリプトを開く必要はありません。

返信の操作系がよくできています。セッションが複数選択肢の質問をしている場合、ピークパネルはオプションを表示し、数字キーを押して1つを選択できます。他のブロックされたセッションの場合は、Tab を押して入力に提案された返信を入力し、送信前に編集できます。返信の前に ! を付けて Bash コマンドを代わりに送信します。

信頼性についての設計も明記されています。バックグラウンドサービスに到達できないか、送信が失敗した場合、返信は保存され、そのプロセスが再度開始されるときにセッションの次のプロンプトとして送信されます。ただし! でプレフィックスされた返信は保存されません。保存されたテキストはセッションにプレーンプロンプトとして到達するため、Bash コマンドとして実行されません。——保存されたコマンドが後から勝手に実行される事故を避ける設計で、妥当だと思います。

フル会話が要るときは**Enter または → でアタッチ**します。アタッチすると、Claude は不在中に何が起こったかの短い要約を投稿します。

アタッチ中の例外が2つ。**バックグラウンドセッションは /install-github-app と /mcp 設定リスト（認証アクションを含む）を拒否します。ただし/mcp reconnect <server>、/mcp enable、および /mcp disable は引き続き機能します。**もう1つは表示で、アタッチされたセッションは、tui 設定に関係なく、常にフルスクリーンモードでレンダリングされます。バックグラウンドセッションには追加するターミナルスクロールバックがないためです。

デタッチ周りは混乱しやすいので整理します。空のプロンプトで ← を押すか、/exit を実行してデタッチし、エージェントビューに戻ります。Ctrl+Z もデタッチしますが開始した場所に戻ります。Ctrl+C は標準的な割り込み動作を保持——実行中の応答または ! シェルコマンドをキャンセルするのであり、デタッチするのではありません。

そして最も大事な一行。デタッチはバックグラウンドセッションを停止しません。止めたければセッション内から /stop を実行します。

← の挙動には待機仕様があります。← を押すときにツールが実行されている場合、Claude Code はそれが完了するまで約10秒待機してからバックグラウンドにし、すぐにバックグラウンドにするには ← を再度押します。ただし10秒の制限は subagents が実行されている間は適用されません。Claude Code は待機を続けるため、それらの作業が引き継がれ、ここで再度 ← を押すとsubagents が最初から再開されます。——待たされるのには理由がある、ということです。

このショートカットは**/config の leftArrowOpensAgents 設定でオフにできます。**

一覧を整理する・絞り込む

Ctrl+S を押してディレクトリでグループ化に切り替えます。選択内容は実行全体で保存されます。グループ内では Ctrl+T でピン留め（アイドル中もプロセスを実行し続ける）、Shift+↑／Shift+↓ で並べ替え、Ctrl+R で名前変更、グループヘッダーで Enter で折りたたみ。

削除は2段階です。Ctrl+X を押して停止し、2秒以内に Ctrl+X を再度押して削除します。ここに破壊的な副作用があるので警告として引用します。削除するとセッションがエージェントビューから削除されます。Claude がワークツリーを作成した場合、削除するとそのワークツリーも削除されます。コミットされていない変更を含みます。保持したい作業をプッシュまたはコミットしてから削除します。

救いは会話トランスクリプトはローカルマシンに残り、claude --resume を通じて利用可能ですという点です。消えるのは作業ツリー側です。

絞り込みはディスパッチ入力に直接打ちます。ディスパッチ入力に入力してディスパッチの代わりにフィルタリングします。

フィルター	表示
a:<name>	名前付きエージェントを実行しているセッション
s:<state>	指定された状態のセッション。例えば s:working。また s:blocked はあなたを待機しているすべてのセッションを受け入れます
#<number> または PR URL	そのプルリクエストで作業しているセッション
その他の URL	最初のプロンプトにその URL が含まれていたセッション

キーボードショートカットは ? で一覧が出ますが、原文の表をそのまま引きます。

ショートカット	アクション
↑ / ↓	行間を移動
Enter	選択したセッションにアタッチするか、入力にテキストがある場合はディスパッチ
Space	選択したセッションのピークパネルを開くまたは閉じる
Shift+Enter	ディスパッチして直ちにアタッチ
→	選択したセッションにアタッチ
Alt+1..Alt+9	フォーカスされたセッションのディレクトリ内のセッション 1〜9 にアタッチ
Tab	空の入力で、すべての subagents を参照します。それ以外の場合はハイライトされた提案を適用
Ctrl+S	グループ化を状態とディレクトリの間で切り替え
Ctrl+T	選択したセッションをピン留めまたはピン留め解除
Ctrl+R	選択したセッションの名前を変更
Ctrl+G	$VISUAL または $EDITOR でディスパッチプロンプトを開く
Ctrl+X	セッションを停止。2 秒以内に再度押して削除
Shift+↑ / Shift+↓	選択したセッションを並べ替え
Esc	ピークパネルを閉じるか、入力をクリアするか、終了
Ctrl+C	入力をクリア。2 回押して終了
?	すべてのショートカットを表示

ディスパッチの3経路

エージェントビューから／既存セッションから／シェルからの3つです。

**(1) エージェントビューから。**入力にプロンプトを打って Enter。**セッションはプロンプトから自動的に名前が付けられます。**プレフィックスで挙動を制御できます。

入力	効果
<agent-name> <prompt>	最初の単語がカスタム subagent 名と一致する場合、その subagent はセッションのメインエージェントとして実行され、frontmatter の設定を使用します
@<agent-name>	プロンプト内の任意の場所でカスタム subagent を言及してメインエージェントとして実行
@<repo>	リポジトリを言及してセッションをそこで実行します
/<command>	skills および commands をディスパッチプロンプトとして提案
! <command>	Claude セッションを開始する代わりに、シェルコマンドをバックグラウンドジョブとして実行します
#<number> または pull request URL	セッションが既にその PR で作業している場合は、ディスパッチの代わりに選択
Shift+Enter	ディスパッチして新しいセッションに直ちにアタッチ

ここに踏みやすい罠が1つ書かれています。**最初の単語の一致も適用されるため、subagent 名の1つと一致する単語で始まるプロンプトはその subagent をディスパッチします。**回避策も原文にあります。明示的にしたい場合は @ 形式を使用するか、プロンプトを別の単語で開始して一致を避けます。

また、エージェントビュー自体で実行される少数のコマンドがあります。/exit と /quit はエージェントビューを閉じ、/logout はサインアウト、/model はディスパッチモデルを設定、/login はサインインダイアログを開きます。それ以外の組み込みコマンドはattach to a session to run it ヒントを表示します。

(2) セッション内から。****/background またはそのエイリアス /bg を実行して現在の会話をバックグラウンドセッションに移動します。/bg にプロンプトを渡して、バックグラウンド化する前に1つの追加命令を送信することもできます。

引き継がれるものが明記されています。実行中のバックグラウンドシェルコマンド、backgrounded subagent、動的ワークフロー、および /loop で作成したスケジュール済みタスクはバックグラウンドセッションに転送され、そこで実行し続けます。一方転送できない作業（実行中の monitor など）は停止されます。その場合はBackground this session? ダイアログを表示するため、停止する前に確認できます。

起動時フラグも引き継がれます。**--mcp-config および --strict-mcp-config / --settings / --add-dir / --plugin-dir / --fallback-model / --allow-dangerously-skip-permissions。**セッション中に /add-dir で追加したディレクトリも同様です。

(3) シェルから。

claude --bg "investigate the flaky SettingsChangeDetector test"

プロンプトは -p 値ではなく、位置引数です。そして--bg を -p または --print と組み合わせることは、セッションが作成される前にエラーで拒否されます。

subagent をメインエージェントにするなら --agent と組み合わせます。

claude --agent code-reviewer --bg "address review comments on PR 1234"

表示名を決めるなら --name。

claude --bg --name "flaky-test-fix" "investigate the flaky SettingsChangeDetector test"

起動すると短い ID と管理コマンドが出力されます。

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

バックグラウンドセッションをホストするサービスがまだ実行されていない場合、--bg はこの出力の上に Starting background service… を最初に出力する可能性があります。

シェルコマンドをジョブとして流す

Claude を呼ばずにコマンドだけ回すこともできます。ディスパッチ入力の先頭で ! を打つと、

! pytest -x

同じことをシェルから直接やるなら、

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

**シェルジョブは Claude の代わりにコマンドを実行するため、モデルは呼び出されず、出力はセッションに送信されません。**保持期間に注意が要ります。キャプチャされた出力はメモリに保持され、ディスクに書き込まれません。行とその出力は、コマンド終了後約5分で自動的にクリーンアップされるため、その前に結果が必要な場合は読み取ります。

ファイル編集はどう分離されるか

第63回の worktree が、ここで自動的に効いてきます。エージェントビュー、/bg、または claude --bg から開始されたすべてのバックグラウンドセッションは、作業ディレクトリで開始されます。ファイルを編集する前に、Claude はセッションを .claude/worktrees/ の下の分離された git worktree に移動するため、並列セッションは同じチェックアウトを読み取ることができますが、それぞれが独自のものに書き込みます。

スキップされる条件は3つ。既にリンクされた git worktree 内にある場合／作業ディレクトリが git リポジトリでなく、WorktreeCreate hook も設定されていない場合／作業ディレクトリの外への書き込みの場合。

分離を切りたい場合はプロジェクトの .claude/settings.json に設定します。

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

分離が効いているセッションには自動化の権限が与えられます。ワークツリーでコード変更を分離したバックグラウンドセッションは、確認を求めずにコミット、独自のブランチをプッシュ、およびドラフトプルリクエストを開きます。歯止めも明示されています。main または master にプッシュすることはなく、強制プッシュまたはマージを行わず、指示があればプルリクエストを開きません。

逆に分離されていないチェックアウトを編集するセッションは、コミットまたはブランチの切り替え前に確認を求めます。——分離されているかどうかで、確認なしに進む範囲が変わる。この対応関係は理解しておくべきところです。

削除方法によるワークツリーの扱いの差も重要です。エージェントビューで Ctrl+X を2回で削除すると、コミットされていない変更を含めてワークツリーが削除されます。対してシェルから claude rm で削除すると、コミットされていない変更があるワークツリーが保持され、セッション行と一緒に保持されます。そしてどちらのパスでも、どこかにプッシュされていないコミットがあるワークツリーは削除されません。

なお、バックグラウンドセッションが生成する subagent は、セッションの作業ディレクトリを継承するため、そのファイル編集はセッションのワークツリーではなく作業コピーに配置されます。subagent にも個別のワークツリーを与えるにはfrontmatter で isolation: worktree を設定するか、生成時に isolation: "worktree" を渡します。

モデル・権限モード・努力

ヘッダーに出ているモデルがディスパッチのデフォルトです。ビュー内で切り替えるなら、ディスパッチ入力に /model とモデル名を打ちます。次の例は1つのセッションを Opus で、次のセッションを Sonnet でディスパッチします。

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

このオーバーライドは現在の claude agents 実行の残りの間続き、設定ファイルに書き込まれません。/model default で解除できます。

ビュー全体のデフォルトは起動フラグで決めます。

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

アクティブなデフォルトはディスパッチ入力の下のフッターに表示されます。

権限モードの決まり方には開始経路による差があります。/bg または ← でインタラクティブセッションをバックグラウンド化すると、現在の権限モードが保持されます。一方エージェントビュー入力からディスパッチするか、シェルから claude --bg を実行すると、そのディレクトリの設定から defaultMode を使用するか、ディスパッチされた subagent の frontmatter から permissionMode を使用します。

bypassPermissions には明確なゲートがあります。セッションが監視していない状態で承認なしに動作することを許可するため、claude で対話的に実行して --dangerously-skip-permissions で受け入れるまで拒否されます。——一度も人が同意していない bypassPermissions は、バックグラウンドでは走らないということです。

努力（effort）の扱いには非対称があります。セッションが effortLevel setting から取得した努力は、--effort または /effort からではなく、ディスパッチで固定されません。セッションのために開始された各プロセスは設定を再度読み取るため、settings.json で effortLevel を編集すると、← または /bg でバックグラウンド化したセッションとそれらの後の再開に到達します。

設定・プラグイン・MCP

各フラグはエージェントビュー自体に適用され、そこからディスパッチするすべてのセッションに渡されます。

フラグ	効果
--settings <file-or-json>	エージェントビューとディスパッチされたセッションの設定をオーバーライド
--add-dir <path>	追加ディレクトリへのファイルアクセスを許可
--plugin-dir <path>	ローカルディレクトリからプラグインを読み込む
--mcp-config <file-or-json>	設定ファイルまたは JSON 文字列から MCP サーバーを読み込む
--strict-mcp-config	--mcp-config からのみ MCP サーバーを使用し、他の MCP 設定を無視

--add-dir、--plugin-dir、または --mcp-config を値ごとに1回繰り返します。--add-dir a b c などのスペース区切り形式は claude agents ではサポートされていません。

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

シェルからの管理コマンド

すべてのバックグラウンドセッションには、シェルから使用できる短い ID があります。各セッションの ID は ~/.claude/jobs/ の下のディレクトリ名です。

コマンド	目的
claude agents	エージェントビューを開く
claude agents --cwd <path>	<path> の下で開始されたセッションにスコープされたエージェントビューを開く
claude agents --json	アクティブなセッションを JSON 配列として出力して終了。--all で完了分も含む
claude attach <id>	このターミナルでセッションにアタッチする
claude logs <id>	セッションの最新出力を出力する
claude stop <id>	セッションを停止する。claude kill も受け入れます
claude respawn <id>	セッションを再開する。会話を保持したまま実行または停止状態から再開します
claude respawn --all	すべての実行中のセッションを再開する
claude rm <id>	セッションをリストから削除する
claude daemon status	supervisor の状態、バージョン、ソケットディレクトリ、およびワーカー数を出力する
claude daemon stop --any	supervisor プロセスとそれがホストするバックグラウンドセッションを停止します

--json の中身は自動化に効きます。各エントリには cwd、kind、startedAt が含まれます。バックグラウンドエントリには、claude attach/logs/stop で使用可能な id と、working、blocked、done、failed、stopped のいずれかの state も含まれます。pid と status はプロセスが生きている間のみ存在し、status が waiting の場合は waitingFor が存在します。

スーパーバイザープロセス — この機能の心臓部

ここが仕組みの核です。バックグラウンドセッションはユーザーごとのスーパーバイザープロセスによってホストされ、ターミナルおよびエージェントビューとは別です。スーパーバイザーはセッションを初めてバックグラウンド化するか、エージェントビューを開くときに自動的に開始され、直接管理することはありません。

起動が速い理由も書かれています。スーパーバイザーは、ディスパッチがコールドローンチの遅延なく開始されるように、1つのプリウォーミングされたワーカープロセスを準備完了の状態で保持しています。

セキュリティ面の言明が1行あり、これは引用しておく価値があります。スーパーバイザーとそのセッションはインタラクティブセッションと同じ認証情報で認証され、モデル API を超えて追加のネットワーク接続を行いません。

ライフサイクルの規則はこうです。アクティブに作業しているセッション、入力を待機しているセッション、またはターミナルが接続されているセッションはプロセスを実行し続けます。そしてセッションが完了し、約1時間アタッチされていない状態で待機すると、スーパーバイザーはリソースを解放するためにプロセスを停止します。例外がCtrl+T でピン留めしたセッション。停止されてもトランスクリプトと状態はディスク上に残り、次回アタッチ、ピーク表示、または返信するときに、スーパーバイザーは中断したところから新しいプロセスを開始します。

さらにすべてのセッションが完了し、ターミナルが接続されていない場合、スーパーバイザー自体が終了します。ホストのメモリが不足している場合、スーパーバイザーはアイドル状態の非ピン留めセッションを最初に停止し、何も解放されない場合のみアイドル状態のピン留めセッションを停止します。

自動更新との関係も設計されています。スーパーバイザーはディスク上にインストールされた Claude Code バイナリを監視し、通常の自動更新プログラムがそれを置き換えた後、新しいバージョンに再開します。これはネットワークチェックではなく、ローカルファイルウォッチです。ただしアクティブに作業しているセッション、入力を待機しているセッション、またはターミナルが接続されているセッションは中断されません。そしてこれらの再開は常にセッションをより新しいバージョンに移動するだけです。

状態の保存先は次のとおり。CLAUDE_CONFIG_DIR を設定した場合はスーパーバイザーは ~/.claude の代わりにそのディレクトリを使用し、独自のセッションを持つ別のインスタンスとして実行されます。

パス	内容
~/.claude/daemon.log	スーパーバイザーログ
~/.claude/daemon/roster.json	実行中のバックグラウンドセッションのリスト。再開後に再接続するために使用
~/.claude/jobs/<id>/state.json	エージェントビューに表示されるセッションごとの状態
~/.claude/jobs/<id>/tmp/	セッションごとのスクラッチディレクトリ。ここへの書き込みは権限確認を促しません。セッションが削除されると削除されます

各バックグラウンドセッションには CLAUDE_JOB_DIR 環境変数が ~/.claude/jobs/<id> ディレクトリに設定されているため、セッションが実行するシェルコマンドは並列セッションと衝突することなく $CLAUDE_JOB_DIR/tmp に一時ファイルを書き込むことができます。

トラブルシューティング（抜粋）

**原文には10節あります。**ここでは遭遇しやすい4つに絞ります。

**claude agents がサブエージェントをリストして終了する。****エージェントビューはお使いの環境では利用できません。claude update を実行して最新バージョンをインストールしてください。**更新しても開かないなら、設定や環境変数でオフになっていないか確認します。

**シャットダウン後にセッションが失敗として表示される。**マシンをシャットダウンまたは再起動すると、実行中のバックグラウンドセッションが停止するため、次にエージェントビューを開くときに失敗として表示されます。それらのいずれかにアタッチ、ピーク表示、または返信すると、セッションは中断したところから再開します。なおスリープだけではこれは発生しません。

**バックグラウンドサービスが応答しない。**スーパーバイザーがスタールしている可能性があるので、止めます。

claude daemon stop --any --keep-workers

--keep-workers がない場合、コマンドはバックグラウンドセッションも終了します。--any フラグは、デフォルトであるインストール済みサービスではなく、オンデマンドで開始されたスーパーバイザーを停止したいことを確認します。Windows では応答しない場合にプロセス ID が出力されるので taskkill /PID <pid> で終了します。

**ディスパッチが Could not resolve authentication method で失敗する。**インタラクティブでは認証できているのにこうなる場合、このエラーはスーパーバイザープロセス自体で利用可能な保存された認証情報がないことを意味します。/login 済みか API キー設定済みかを確認したうえで、同じコマンドでスーパーバイザーを止め直します。環境変数で認証する場合は、変数が設定されているシェルからその次のコマンドを実行してください。

このほか、macOS で ~/Desktop・~/Documents・~/Downloads が読めない（System Settings の Privacy & Security でアクセス許可が必要）、macOS 15 以降でローカルネットワークに到達できない、プロンプトが4文字未満で Too short として拒否される、.claude/worktrees/ が満杯になる、といった節があります。詳細は原文を参照してください。

バージョン履歴について

原文末尾には v2.1.139 から v2.1.208 までの16行のバージョン履歴表があります。分量が大きいため本記事では引用しませんが、位置づけだけ書いておきます。claude agents はまだサポートしていないフラグを unknown option エラーで拒否します。つまりフラグが効かないときはバージョンを疑うのが正しい順序です。主要な節目だけ挙げると、v2.1.139 で導入、v2.1.141 で --cwd、v2.1.142 で --permission-mode／--model／--effort／--settings／--add-dir／--plugin-dir／--mcp-config 系、v2.1.143 で worktree.bgIsolation、v2.1.157 で --agent、v2.1.198 で通知とドラフト PR の自動作成が入っています。

4. まとめ ＋ 次回予告

• エージェントビューは**claude agents で開く、すべてのバックグラウンドセッションの一枚の画面**。リサーチプレビューで v2.1.139 以降が必要。
• 各バックグラウンドセッションは完全な Claude Code の会話で、ターミナルが接続されていなくても実行し続ける。
• 基本ループは**ディスパッチ → 行を眺める → Space でピークして返信 → 必要なら Enter/→ でアタッチ → ← でデタッチ。****デタッチは停止ではない。**止めるのは /stop。
• アイコンは色で状態、形で「プロセスが生きているか」を示す。∙ は死んでいるのではなくいつでも起こせる。
• 行の1行要約は Haiku クラスモデルが書いており、課金対象。サードパーティプロバイダーで Haiku 未設定ならメインモデルにフォールバックする。
• 結果の受け取り口は多くの場合 PR 列。番号が緑になったらレビューしてマージ。
• ディスパッチは3経路——**ビューの入力／セッション内の /bg／シェルの claude --bg。**プレフィックス @・!・/ で挙動が変わる。最初の単語が subagent 名と一致すると意図せずそれが起動する点に注意。
• バックグラウンドセッションは書き込み前に .claude/worktrees/ へ自動退避される。分離済みなら確認なしでコミット・プッシュ・ドラフト PR まで進むが、main/master へのプッシュ・強制プッシュ・マージはしない。
• Ctrl+X 2回の削除はワークツリーごと消す（未コミット変更を含む）。claude rm は未コミット変更があれば残す。
• bypassPermissions は、事前に対話セッションで1回受け入れるまでバックグラウンドでは拒否される。
• 裏側はユーザーごとのスーパーバイザープロセス。プリウォーミングされたワーカーを1つ保持し、完了後約1時間アイドルのセッションはプロセスを停止（ピン留めは除外）、バイナリ更新をローカル監視して新バージョンへ再開する。
• 最大の制約はクォータ。10 個並列に回せばクォータは 10 倍速く減る。そしてセッションはローカル——シャットダウンで止まる。

次回予告（暫定）：第64回で挙げた4アプローチのうち未執筆のエージェントチーム（agent-teams）を取り上げ、共有タスクリストとエージェント間メッセージング、そしてチームメイトが worktree で分離されないことの帰結を扱う予定です。

---