Claude Codeでサブエージェントの確認間隔を設定する

バックグラウンドで動くサブエージェントの様子を見るようClaudeに促すリマインダーの間隔は、CLAUDE_CODE_WORKER_CHECKIN_SCHEDULEで決めます。Claude Codeのv2.1.283以降で使える変数で、前提としてCLAUDE_AUTO_BACKGROUND_TASKSを1にしておきます。以前のCLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSはv2.1.283で削除されました。旧名のまま設定しているファイルがあれば、書き換えが必要です。

旧名の設定が残っていないか確かめる

環境変数リファレンスの旧変数の行には、「Removed in v2.1.283. Use CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE instead」とだけ書かれています。旧名は削除済みなので、更新後にリマインダーが来なくなったと感じたら、まずsettings.jsonやシェルのプロファイルに旧名が残っていないかを探します。

旧名が残っているかどうかは、設定ファイルとプロファイルを検索すれば分かります。

grep -rn "AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS" ~/.claude/settings.json .claude/ ~/.zshrc ~/.bashrc 2>/dev/null

何も出なければ、旧名は残っていません。行が出たら、変数名をCLAUDE_CODE_WORKER_CHECKIN_SCHEDULEに置き換えます。

設定する手順

シェルで一時的に試すなら、次のようにexportしてから起動します。

export CLAUDE_AUTO_BACKGROUND_TASKS=1
export CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE=600,1800,3600
claude

毎回のセッションで固定したい場合は、settings.jsonのenvキーに書きます。envキーの値は、シェルでexportしていなくても読まれます。ただしClaude Desktopアプリやセルフホストのランナーがセッションを起動する場合、起動環境がすでに設定している変数についてはenvの値が無視されます。

{
  "env": {
    "CLAUDE_AUTO_BACKGROUND_TASKS": "1",
    "CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE": "600,1800,3600"
  }
}

シェルでexportした値は、そのターミナルを閉じると消えます。恒久的に使うなら、~/.zshrcなどにexport行を足すか、上のsettings.json方式にします。

Windowsでは、PowerShellの$env:やコマンドプロンプトのsetで環境変数を渡すのが一般的な書き方です。変数名と値は上のexportの例と同じものを使います。

settings.jsonのenvは、起動し直さなくても反映されます。保存すると、動いているセッションの環境に新しい値や変更後の値が適用される仕組みです。一方、ファイルから変数を消した場合の扱いは、設定リファレンスに書かれていません。旧名を消す作業をしたあとは、一度立ち上げ直すと状態をそろえられます。

設定が入ったかどうかは、起動前に同じシェルで値を出して確かめます。

echo $CLAUDE_CODE_WORKER_CHECKIN_SCHEDULE

複数の値は「次のリマインダーまでの待ち」

環境変数リファレンスでは、並べた各値を「次のリマインダーまでの待ち」、最後の値を「以降繰り返される値」と説明しています。600,1800,3600なら、次のような間隔になります。

値が1つだけなら、その間隔で一定のリマインダーになります。何も設定しなければ、リマインダーは来ません。

値の書式で未設定扱いになる

この変数が受け付けるのは、1〜86400(24時間)のプレーンな数字だけです。それ以外の値や書き方は、未設定として読まれます。リマインダーが来ないときは、値の書式を最初に疑います。

たとえば「5分おき」のつもりで5mと書いても、数字として読まれず未設定です。秒に直した300と書きます。2時間なら7200、上限の24時間なら86400です。桁区切りの86_400や指数表記の1e3も、プレーンな数字ではないため同じ扱いになります。範囲外の0や90000も該当します。

他の数値系の環境変数には桁区切りなどを受け付けるものがあるため、値をコピーして使い回すときは注意が要ります。

前提になるバックグラウンドの動き

サブエージェントを前景と背景のどちらで動かすかは、状況で変わります。インタラクティブセッションでは、フォーク・モードが既定でオンです(v2.1.232以降)。このときClaudeが生成するサブエージェントはバックグラウンドで動き、Claude自身はフォアグラウンドを要求できません。

-pを付けた非対話モードとAgent SDKでは、フォーク・モードが既定でオフです。この場合、Claudeは結果をすぐ必要とするときだけフォアグラウンドで走らせます。

バックグラウンドのサブエージェントは、使える組み込みツールが絞られます。MCPツールはそのまま使えます。組み込みツールはRead・Grep・Glob・LSP・Bash・PowerShell・Edit・Write・NotebookEdit・WebFetch・WebSearch・TodoWrite・Skillなどに限られます。LSPが使えるのはv2.1.280以降です。toolsで絞った結果、使えるツールが1つも残らないときは、通常はエラーで起動しません。

フォーク・モードはCLAUDE_CODE_FORK_SUBAGENTで切り替えられます。1なら非対話モードとAgent SDKでもオンになり、0ならあらゆるセッションでオフです。オンの状態では、Claude CodeがAgentツールのrun_in_backgroundパラメータを外すため、Claudeがフォアグラウンドを選ぶ余地はありません。一方、フロントマターでbackground: trueを指定したサブエージェントは、フォーク・モードがオフでも、バックグラウンドに置かれます。

サブエージェントが入れ子になっている場合の挙動も、セッションの種類で変わります。インタラクティブセッションでは、サブエージェントが起動したバックグラウンドのサブエージェントの完了を、起動元が待ってから終わります。非対話モードとAgent SDKでは待たないため、起動元の終了後に完了した入れ子のサブエージェントは、メインの会話に報告します。

権限が必要なツール呼び出しでは、確認プロンプトがメインのセッションに表示され、どのサブエージェントが求めているかも示されます。承認すれば続行し、Escを押すとそのツール呼び出し1回だけが拒否されます。サブエージェントは止まりません。

セッション中ずっと有効になる許可のように、その1回を超えて続く選択肢を選んだ場合は、答えがメインの会話を含むセッション全体に適用されます。1回限りの拒否と比べると、影響する範囲が大きく違います。

結果は完了通知として、後のターンにClaudeへ届きます。進捗を尋ねても、通知が来るまでClaudeは「まだ実行中」と答えます。v2.1.211より前は、未完了のサブエージェントの結果をClaudeが報告してしまうことがありました。リマインダーは、まだ動いているサブエージェントをClaudeに見に行かせるためのものです。

手動でバックグラウンドへ回したいときは、Ctrl+Bを押します。回したタスクは/tasksに並びます。完了したサブエージェントは「done」として30秒間だけ残ります。失敗したものや手動で止めたものは、一覧からすぐ消えます。

似た変数との違い

名前の近い変数がいくつかあり、役割も時間の単位も違います。

CLAUDE_CODE_GOAL_CHECKIN_MINUTESは/goalの確認、CLAUDE_CODE_WORKER_CHECKIN_SCHEDULEはサブエージェントの様子見で、対象が異なります。分と秒の取り違えにも注意が必要です。

CLAUDE_CODE_DISABLE_BACKGROUND_TASKSを1にすると、サブエージェントはあらゆるセッションでフォアグラウンドで動きます。バックグラウンド自体がなくなるため、確認間隔を設定しても働く対象がありません。

設定ファイルとシェルの優先順位

同じ変数をシェルとsettings.jsonのenvの両方に書いたときは、ほとんどのセッションで設定ファイルの値が使われます。envの各項目は、シェルから引き継いだ値を置き換えてプロセス環境に書き込まれるためです。例外になるセッションは、設定リファレンスの「How env values interact with your shell」に載っています。

設定ファイルどうしの順は、強い方から次のとおりです。

1. 組織が配布する管理設定(managed settings)
2. 起動時のコマンドライン引数
3. .claude/settings.local.json(プロジェクト内の個人用)
4. .claude/settings.json(チーム共有)
5. ~/.claude/settings.json(ユーザー全体)

複数人のプロジェクトで同じ間隔を使わせたいなら、チーム共有の.claude/settings.jsonに書いてリポジトリに入れる方法があります。個人のシェルプロファイルに頼ると、人によって未設定の状態が生まれます。

どんな運用に向くか

複数のサブエージェントへ調査や検証を並行して任せ、長く走らせる運用では、リマインダーがあるとClaudeが様子を見る機会が生まれます。リマインダーがなければ、Claudeは完了通知が届くまで、動いているサブエージェントの様子を見に行きません。

間隔を短くしすぎると、確認のたびにメインの会話のターンが増えると考えられます。たとえば30のように数十秒おきにすると、本来の作業指示に使うターンが削られることがあります。最初は300,1800,3600のように、最初だけ短く、あとは間隔を広げる値から試す形があります。

1回きりの通知で足りる場面なら、一回きりのリマインダーを設定する方法の方が単純です。