claude agents --jsonでバックグラウンドセッションを操作する

CIのジョブから「今バックグラウンドで何本のClaude Codeセッションが動いているか」を確認したいとき、TUI(ターミナルUI)のclaude agentsは使えません。対話画面が前提のビューだからです。答えはclaude agents --jsonで、セッション一覧をJSON配列として出力してすぐ終了します。

agent viewのアイコン・キーバインド・ディスパッチ構文は別記事で扱いました。本稿は、そのTUIを開かずにセッションを取得・起動・隔離するスクリプト向けのレイヤーに絞って掘り下げます。

背景

claude agentsはセッションを人間が眺めるためのTUIとして登場しましたが、その裏側にあるフラグと仕様は、CIやフックからバックグラウンドセッションを制御する用途にも育っています。

TUIを直接操作しないという前提に立つと、押さえるべき仕様は「JSON出力の中身」「シェルから起動・制御するコマンド」「ファイル編集がどう隔離されるか」「セッションをどう取り戻すか」の4つに整理できます。

claude agents --jsonでセッションを取得する

claude agents --jsonは、稼働中のセッション(対話セッションと、プロセスが終了していても作業中・ブロック中のバックグラウンドセッション)をJSON配列で出力して終了します。完了済みのセッションまで含めたいときは--allを、特定ディレクトリ配下だけに絞りたいときは--cwd <path>を付けます。

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

各エントリのフィールドは次のとおりです。

--add-dirと--mcp-configはagentsより後ろに置く必要があります。前に置くとclaude agents --jsonがunknown optionエラーで落ちます。--settingsと--plugin-dirは前後どちらでも構いません。

シェルからセッションを起動・制御する

バックグラウンドセッションにはそれぞれ短いIDが振られ、~/.claude/jobs/配下のディレクトリ名と一致します。agent viewを開かずに、このIDだけでスクリプトからセッションを操作できます。

claude --bg "flaky testを調査して"        # 新規バックグラウンドセッションを起動
claude attach <id>                         # このターミナルにアタッチ
claude logs <id>                           # 直近の出力を表示
claude respawn <id>                        # 会話を保ったまま再起動
claude respawn --all                       # 稼働中の全セッションを一括再起動
claude rm <id>                             # 一覧から削除
claude daemon status                       # 常駐プロセス(supervisor)の状態を表示

--bgには--name・--agent・--permission-modeを組み合わせられます。--nameを付けると起動直後の出力にその名前が入り、--agentは定義済みのサブエージェントをセッション本体として使います。

Claudeの応答を介さずシェルコマンドだけをバックグラウンドで走らせたいときは--execを使います。モデルは呼ばれず、出力はどのセッションにも送られません。

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

このジョブはPTY(疑似端末)経由の行として一覧に現れ、claude logs <id>で結果を確認できます。出力はメモリ上だけに保持され、コマンド終了から約5分で行ごと自動的に片付きます。

--dangerously-skip-permissionsをclaude --bgやclaude agentsに渡すには、事前の同意が要ります。対話セッションでclaude --dangerously-skip-permissionsを一度実行し、バイパスの免責事項に同意している必要があります。同意済みでない場合はエラーではなく、同じ免責事項ダイアログが表示されます。

ディスパッチの既定値をフラグで指定する

agent viewから起動するセッション全体に既定値を与えたいときは、claude agentsを開く時点で--permission-mode・--model・--effort・--agentを渡します。

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

--agentは、ディスパッチしたプロンプトが@名前でサブエージェントを指定しなかったときに使われるセッション本体の役割です。指定がなければagent設定の値、それも無ければ組み込みのclaudeエージェントが使われます。現在の既定値はagent view下部のフッターに常に表示されるため、スクリプトから起動する前に確認できます。

常駐プロセスそのものを止めたいときはclaude daemon stop --anyを使います。--keep-workersを付けると、バックグラウンドセッション自体は動かしたまま供給プロセスだけを終了させられます。次にclaude agentsかclaude --bgを実行したタイミングで、新しい常駐プロセスが既存セッションへ再接続します。デプロイでClaude Codeのバイナリだけを更新し、走っているセッションは落としたくない場面に向いた手順です。

claude daemon statusは、常駐プロセスの稼働状態・バージョン・ソケットディレクトリ・ワーカー数を出力します。CIの障害調査で「そもそも常駐プロセスが生きているか」を切り分けたいとき、claude agents --jsonより先に叩く価値がある軽いコマンドです。

バックグラウンドセッションのファイル編集はどう隔離されるか

claude --bg・/bg・agent viewのいずれで起動しても、セッションはまず現在の作業ディレクトリで始まります。ファイルを編集する直前、Claudeはセッションを.claude/worktrees/配下の独立したgit worktreeへ移します。並列に走る他セッションと同じチェックアウトを読みながら、書き込みだけを分離する仕組みです。

隔離をスキップするのは次の場合です。

git worktreeが運用上使いにくいリポジトリでは、settings.jsonのworktree.bgIsolationを"none"に設定して隔離自体を止められます。

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

セッションをCtrl+X2回押し、またはclaude rmで削除するとき、Claudeが作成したworktreeの扱いは経路で変わります。agent viewからの削除はコミットしていない変更ごと消しますが、claude rmは未コミットの変更がある限りworktreeとセッション行を残します。未pushのコミットがある、または他セッションが使用中のworktreeは、どちらの経路でも消えず理由が示されます。

停止したセッションを取り戻す

セッションを完全に失っても、復旧の入口は3つ用意されています。

/fork: 実行中の会話をコピーして新しいバックグラウンドセッションを作り、元のセッションは動いたまま残ります(v2.1.212以降)。モデル・権限モード・エフォートレベルと、セッション中に追加したディレクトリや「今後聞かない」権限も引き継ぎます。ただしシステムプロンプトを置き換えたセッションや--tools許可リスト付きで起動したセッションはコピーできず、その旨が示されます。

agent view内の/resume: 空の/resumeと入力すると、一覧から削除したものも含めて開いていたリポジトリの過去セッションをピッカーで選べます(v2.1.212以降)。選んだセッションはバックグラウンドセッションとして一覧に復帰します。

claude --resume: agent viewを介さず、削除済みセッションのトランスクリプトからシェル直接で再開する経路です。

claude agents --jsonが変えたCI連携

--json・--cwd・--execが揃ったことで、claude agentsは「人が眺めるTUI」から「スクリプトが問い合わせる状態ストア」へ役割を広げています。JSON出力のstateフィールドをポーリングすれば、CIパイプラインは対話画面なしにバックグラウンドセッションの完了を待てます。

象徴的なのは--execの存在です。モデルを一切呼ばずシェルコマンドだけをジョブとして扱うこの仕組みは、agent viewが「Claudeセッションの一覧」ではなく「非同期ジョブ全般の一覧」を志向していることを示しています。テスト実行やビルドのような重いシェル処理を、Claudeへの依頼と同じ一覧・同じIDの仕組みで管理できる設計です。

つまずきやすい点

--add-dirの位置で--jsonがエラーになる

--add-dirや--mcp-configをagentsより前に置くと、claude agents --jsonはunknown optionエラーで終了します。スクリプトに組み込むときはフラグの並び順をclaude agents --json --add-dir <path>のように固定します。

ゲートウェイの環境変数が引き継がれない

ANTHROPIC_BASE_URLのようなLLMゲートウェイの環境変数は、条件付きでしか転送されません。転送されるのは、supervisorを起動したシェルの環境にゲートウェイが含まれ、かつディスパッチ先が同じディレクトリである場合だけです。@repoや--cwdで別ディレクトリへディスパッチした場合は転送されず、そのプロジェクトのsettings.jsonのenvブロックが代わりにエンドポイントを供給します。

停止したセッションのプロセスをkillしてしまう

killコマンドで自分がバックグラウンドしたセッションのプロセスを直接終了すると、supervisorはそのセッションを再起動せずstoppedとして扱います。一方、claude --bgやagent viewの入力からタスク付きで起動したセッションは、依頼を完了させるため自動的に再起動されます。

よくある質問

JSON出力をポーリングする以外に完了を検知する方法はありますか?

セッションが対話中に完了・失敗すると、設定済みの通知チャネル経由で通知されます。ポーリングと通知チャネルを併用すると、CIとローカル両方で完了を取りこぼしにくくなります。

--execジョブの出力はディスクに残りますか?

残りません。出力はメモリ上だけに保持され、コマンド終了から約5分で行ごと自動的に削除されます。結果を保存したいスクリプトは、その間にclaude logsで取得する必要があります。

claude respawn --allはどんなときに使いますか?

Claude Codeのバイナリを更新したあと、稼働中の全バックグラウンドセッションを新しいバイナリへ一括で移すときに使います。会話は個別セッションのまま維持されます。

worktree隔離を止めるとファイルの競合はどう防ぎますか?

worktree.bgIsolationを"none"にすると、並列セッションが同じファイルを同時に編集するリスクは自分で管理する必要があります。同じファイルを触りうるセッションを同時に走らせない運用が前提になります。

まとめ

claude agents --json・--cwd・--execは、agent viewを対話画面の外からスクリプトで扱うための入口です。JSON出力のフィールド、フラグの並び順、ファイル編集の隔離ルール、/forkと/resumeによる復旧経路を押さえておくと、CIやフックからバックグラウンドセッションを安全に制御できます。定期実行する監査やレビューを組む場合は、Routinesによるスケジュール実行と組み合わせる設計も検討する価値があります。起動したセッションに@メンションで直接メッセージを送りたい場合は、Claude Codeの@メンション入力も合わせて確認してください。