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

CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSは、CLAUDE_AUTO_BACKGROUND_TASKSが有効な環境で、バックグラウンドで走っているサブエージェントの様子を確認するようClaudeに促すリマインダーの間隔を秒単位で決める環境変数です。Claude Code v2.1.248以降で使えます。設定しなければリマインダーは一切発生せず、Claudeが自分から進捗を報告しに来ることはありません。

このTipsでできること

バックグラウンドで長時間走るサブエージェントに対して、Claudeが定期的に「まだ動いているか」を確認しに行くようになります。放置されたサブエージェントの結果を取りこぼしにくくする設定です。

やり方

CLAUDE_AUTO_BACKGROUND_TASKSを有効にした上で、確認間隔を秒単位で設定します。値は1〜86400(24時間)の整数のみを受け付けます。

export CLAUDE_AUTO_BACKGROUND_TASKS=1
export CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS=120
claude

毎回のセッションで固定したい場合は、シェルではなくsettings.jsonのenvキーに書きます。設定ファイルに書いた値はどの起動方法でも反映されます。

{
  "env": {
    "CLAUDE_AUTO_BACKGROUND_TASKS": "1",
    "CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS": "120"
  }
}

CLAUDE_AUTO_BACKGROUND_TASKSを1にすると、約2分以上動き続けたサブエージェントが自動でバックグラウンドへ移ります(非対話モードでは長いMCPツール呼び出しも対象です)。確認間隔の変数は、この自動バックグラウンド化とセットで使うことを前提にした設定です。単独で設定しても、CLAUDE_AUTO_BACKGROUND_TASKSが無効なままではリマインダーは働きません。

シェルでexportした値はそのターミナルセッション限りで、新しいターミナルを開くたびに消えます。恒久的に使いたいなら~/.bashrcや~/.zshrcにexport行を追記するか、上のsettings.json方式に切り替えます。設定できたかどうかは、claudeを起動する前に同じシェルで値を出力して確認します。

echo $CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS

Windowsでは書き方が異なります。PowerShellなら$env:CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS = "120"、コマンドプロンプトならset CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDS=120で同じ値を設定できます。恒久化するならPowerShellの[Environment]::SetEnvironmentVariable(...)かコマンドプロンプトのsetxを使います。ただ、OSやシェルをまたいで同じ設定を使えるsettings.json方式の方が管理は楽です。

数値の指定方法に落とし穴がある

Claude Codeの数値系環境変数の多くは2e3のような指数表記や64_000のような桁区切り表記も受け付けますが、CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSは例外で、プレーンな整数だけを受け付けます。指数表記や桁区切りを含む値、あるいは1〜86400の範囲外の値を渡すと、そのままエラーにはならず「未設定」として扱われます。設定したつもりでリマインダーが来ない場合は、まずこの値の書式を疑うのが早道です。

たとえば「5分おき」のつもりで5mや5_00と書いても、数値として解釈できないため未設定扱いになります。正しくは秒に換算した300という値です。同様に「2時間おき」なら7200、「1日1回」なら上限の86400を指定します。他の数値系変数と同じ感覚で桁区切りの86_400と書いてしまうミスも起きやすいので、コピー&ペーストで値を使い回すときは特に注意してください。

指数表記を受け付ける他の数値系変数では、v2.1.211より前のバージョンで1e6のような値が意図せず極端に小さい値(この例では1)として解釈されるバグがありました。この変数がなぜプレーンな整数だけしか受け付けないのかは公式ドキュメントに明記されていませんが、結果としてこの手の書式ミスは「未設定」として扱われ、意図しない極端な値でリマインダーが暴走したり、逆に来なくなったりすることは避けられています。

補足: バックグラウンドサブエージェントの前提知識

サブエージェントは、Claudeがフォアグラウンドとバックグラウンドのどちらで実行するかを状況に応じて自動で切り替えます。インタラクティブセッションでは既定でフォーク・モードが有効になっており、この状態ではClaudeが生成するサブエージェントは常にバックグラウンドで実行され、Claude自身がフォアグラウンド実行を要求することはできません。フォーク・モードが無効な場合(-pを付けた非対話モードやAgent SDKが既定)は、Claudeが結果をすぐに必要とするときだけフォアグラウンドで動きます。

バックグラウンドで動くサブエージェントは、フォアグラウンドより使える組み込みツールが絞られます。MCPツールはそのまま維持されますが、組み込みツールはRead・Grep・Glob・LSP・Bash・PowerShell・Edit・Write・NotebookEdit・WebFetch・WebSearch・TodoWrite・Skillなど一部に限られ、それ以外の組み込みツールは自動で除外されます。LSPがこの一覧に含まれるようになったのはv2.1.280以降で、それより前のバージョンではバックグラウンドのサブエージェントからLSPは使えませんでした。toolsフィールドで許可ツールを絞り込んだ結果、この絞り込みと重なって使えるツールが1つも残らない場合は、サブエージェントの起動自体がエラーになります。

サブエージェントが権限を必要とするツール呼び出しに達すると、確認プロンプトはメイン セッション側に表示され、どのサブエージェントが求めているかも併せて示されます。承認すればサブエージェントは続行し、Escを押せばそのツール呼び出し1回だけを拒否してサブエージェント自体は止めずに済みます。バックグラウンドサブエージェントの結果は、完了通知という形で後続のターンにClaudeへ届きます。進捗を尋ねても、通知が届くまでClaudeは「まだ実行中」としか答えられません。v2.1.211より前のバージョンでは、この完了前の問い合わせに対してClaudeが未完了のサブエージェントの結果を報告してしまう不具合がありました。

キーボードから手動でバックグラウンド化したい場合は、Ctrl+Bを押すと実行中のタスクを裏に回せます。バックグラウンドに回ったサブエージェントは/tasksに一覧表示され、完了すると「done」として30秒間だけ一覧に残った後に消えます。失敗したサブエージェントや手動で止めたサブエージェントは、この一覧からすぐに消える点が完了時と異なります。

関連する環境変数との違い

似た名前の環境変数がいくつかあり、役割が異なります。

CLAUDE_CODE_MCP_AUTO_BACKGROUND_MSはMCPツール呼び出しそのものがバックグラウンドへ移るまでの待ち時間で、単位もミリ秒と異なります。確認間隔の変数はあくまで「移った後、様子を見に行くまでの周期」を決めるものなので、両者を混同すると狙った動作になりません。

settings.jsonで同じ変数を複数のファイルに書いた場合、優先順位は組織管理下の設定(managed settings)が最も強く、次に起動時のコマンドライン引数、その下がプロジェクト個人用の.claude/settings.local.json、さらにチームで共有する.claude/settings.json、最後にユーザー全体の~/.claude/settings.jsonという順に決まります。シェルのexportとファイルのenvキーが両方とも同じ変数を設定していた場合は、ファイル側の値が優先されます。CIのように複数人・複数プロジェクトで同じ間隔を使わせたいなら、個人のシェルプロファイルではなくチーム共有の.claude/settings.jsonに書いてリポジトリへコミットする方が、意図しない未設定状態を防げます。

具体的にはどう動くか

複数のサブエージェントに調査や検証を並行して任せる場面を考えます。CLAUDE_AUTO_BACKGROUND_TASKSだけを有効にした状態では、2分を超えたサブエージェントは黙ってバックグラウンドへ移り、完了するまでClaudeから自発的な報告は来ません。長時間かかるサブエージェントが増えるほど、どれが動いていてどれが止まっているのかをClaude自身が見失いやすくなります。

CLAUDE_CODE_AUTO_BACKGROUND_WORKER_CHECKIN_SECONDSを併せて設定すると、指定した秒数ごとに、まだ動いているバックグラウンドサブエージェントの様子を確認するようClaudeへ促しが入ります。ユーザー側が明示的に「進捗どう?」と尋ねなくても、Claudeの方から様子見のサイクルが回る点が、この変数を設定する主な効果です。

一方で、間隔を極端に短くすると、リマインダーの分だけメイン会話のターンが増えます。数十秒に1回のペースで確認が入ると、Claudeが本来の作業指示に集中する時間が削られるため、体感を見ながら調整するのが現実的です。逆に上限の86400秒(24時間)近くまで伸ばすと、確認は事実上ほぼ働かなくなり、CLAUDE_AUTO_BACKGROUND_TASKSだけを有効にした状態とほとんど変わらなくなります。

どのチームに効くか

CIやバッチ処理でClaude Codeを長時間走らせ、途中で複数のサブエージェントに調査や検証を任せる運用では、確認間隔を短めに設定しておくと、動き続けているサブエージェントの様子を早めに確認できます。逆に対話的に1つずつ確認しながら進めるスタイルでは、そもそもCLAUDE_AUTO_BACKGROUND_TASKSを有効にする理由が薄く、この変数の出番もありません。

記事執筆や大量ファイルのリファクタリングのように、1回のセッションで数十件規模のサブエージェントを次々に立ち上げる運用でも、確認間隔を設定しておくメリットがあります。個々のサブエージェントの完了を逐一待たずに次の指示へ進めつつ、Claude側の定期確認で取りこぼしを防げるためです。設定自体は環境変数1つで完結するので、既存の運用に後から足しても影響範囲は小さく済みます。

-pを付けた非対話モードやAgent SDK経由の実行では、フォーク・モードが既定で無効なため、Claudeが結果をすぐに必要とするサブエージェントはフォアグラウンドで動きます。

まずはCLAUDE_AUTO_BACKGROUND_TASKS=1と組み合わせて、60〜300秒程度の間隔から試すのが無難です。手元のタスクの平均実行時間に合わせて調整してください。

1回限りの通知だけで足りる場面では、この変数よりClaude Codeで一回きりのリマインダーを設定する方法の方が単純です。周期的な様子見が必要なバックグラウンド運用のときだけ、本記事の変数を使う判断になります。