Claude Codeがアイドルになったら1回だけ通知してくれるように──notify_when_idleの仕組み

2026年8月27日、GitHubの公式リリースノート（anthropics/claude-code）を実際に開いて確認した内容です。 v2.1.236（2026年8月19日公開）の変更点一覧に、次の記載があります（原文と訳）。

"Added notify_when_idle to cross-session SendMessage: ask another Claude Code session on this machine to send one notice when it next goes idle — opt-in, one-shot, no polling (macOS and Linux)"

（訳：クロスセッションのSendMessageにnotify_when_idleを追加。同じマシン上の別のClaude Codeセッションに、次にアイドルになった時に1回だけ通知を送るよう頼める。オプトイン・一回限り・ポーリング不要（macOSとLinux））

3行まとめ

• SendMessage（複数のClaude Codeセッション間でメッセージをやり取りする機能）に、notify_when_idleという新しいオプションが追加された
• 「同じマシン上の別セッションが次にアイドル状態になったら、1回だけ通知を送ってほしい」と頼める仕組みで、オプトイン制（明示的に頼まない限り送られない）、通知は1回限り、ポーリング（定期的な確認）を必要としない設計
• 対応OSはmacOSとLinuxの2つと明記されており、Windowsについての言及はない

どんな場面で使うものか

Claude Codeでは、複数のセッションを並行して立ち上げ、それぞれに別々のタスクを任せる使い方ができます。長時間かかるタスク（大規模なリファクタリング、テストの実行、ビルドの完了待ちなど）を1つのセッションに任せている間、別のセッションで別の作業を進める、という運用は珍しくありません。

このとき、「あのセッションのタスクが終わったかどうか、定期的に見に行く」という確認作業は手間になります。notify_when_idleは、この確認作業を「頼んでおけば、終わった時に知らせてくれる」という形に変える仕組みです。

「ポーリング不要」という設計の意味

リリースノートが「no polling（ポーリング不要）」と明記している点は、実装上の設計思想を示しています。ポーリングとは、一定間隔で対象の状態を繰り返し確認する方式のことで、実装が単純な一方、確認頻度と検知の即時性・システム負荷のトレードオフが常につきまといます。notify_when_idleがポーリングを使わずに実現されているということは、セッション側の状態変化（アイドルになった瞬間）をイベントとして検知し、その時点で能動的に通知する仕組みになっていると推測されますが、具体的な実装方式（イベント通知の仕組みなど）については、今回確認したリリースノートの1行には記載がありませんでした。

オプトイン・一回限りという制約

notify_when_idleは「opt-in（オプトイン）」であり、頼まれた側のセッションは、明示的にこの通知を要求されない限り、勝手に他のセッションへ通知を送ることはありません。また「one-shot（一回限り）」という記載から、1度アイドルになって通知を送ったら、それで終わりという設計だと分かります。継続的に「アイドルになるたびに毎回通知する」という用途には使えない、という制約です。

対応OS：発表時はmacOSとLinuxのみ、通信の実装方式もOSごとに違う

リリースノートの末尾に「(macOS and Linux)」という注記があり、公開時点（v2.1.236、2026年8月19日）ではWindowsでの対応が明記されていません。公式ドキュメントで、クロスセッション通信自体の実装方式を確認すると、その理由が推測できる記述があった。

"On this machine: Over a per-session socket on macOS and Linux, or a per-session named pipe on native Windows, never through Anthropic servers."

（同一マシン上：macOSとLinuxではセッションごとのソケット経由、ネイティブWindowsではセッションごとの名前付きパイプ経由。いずれもAnthropicのサーバーを経由しない）

macOS・Linuxとネイティブ Windowsとで、同一マシン内通信の実装方式（Unixドメインソケット対名前付きパイプ）自体が異なっており、notify_when_idleのようにOSごとに実装を分けて機能追加していく必要がある構造だとうかがえる。なお、クロスセッションメッセージング自体は「macOS・Linux・WSL 2内のLinuxはv2.1.224以降、ネイティブWindowsはv2.1.234以降」で利用可能になっており、notify_when_idle（v2.1.236以降）はこの土台の上に追加された機能だ。現在確認できる公式ドキュメントのnotify_when_idle専用セクションには、macOS・Linux限定という当初のOS制限の記載が見当たらず、「Claude Code v2.1.236以降が両方のセッションに必要」という条件のみが書かれている。これが「その後Windowsにも対応が広がった」ことを意味するのか、単にドキュメント側でOSごとの詳細な書き分けを省略しているだけなのかは、今回確認した範囲の記述だけでは判別できなかった。

「アイドル」の定義、通知の中身、実装の仕組み──専用ドキュメントで判明

公式ドキュメント「Message your other Claude Code sessions」に、notify_when_idle専用の見出しセクションがあり、リリースノート1行では分からなかった具体的な仕様が説明されていた。

まず「アイドル」の定義そのものが明記されている。

"Idle here means the session finished a turn with nothing queued."

（ここでの「アイドル」とは、そのセッションが1ターンを完了し、何もキューに残っていない状態を指す）

仕組みについても、ポーリングを使わない理由が具体的に書かれている。

"Claude subscribes with the SendMessage tool's notify_when_idle input, either attached to a message it's sending anyway or on its own. On its own, Claude Code subscribes without starting a turn or spending tokens in the watched session, and sends the notice right away if that session is already idle."

（Claudeは、SendMessageツールのnotify_when_idleという入力パラメータを使って購読する。これは、どのみち送るメッセージに付随させることも、単独で使うこともできる。単独の場合、Claude Codeは監視対象セッションでターンを開始したりトークンを消費したりすることなく購読し、そのセッションが既にアイドルであればすぐに通知を送る）

つまり、「アイドルかどうか」を定期的に問い合わせる（＝ポーリングする）のではなく、セッション側の状態変化に「購読（subscribe）」する形で実装されている、という理解が裏付けられた。

通知が実際にどんな形で届くかも明記されている。OSのシステム通知のような外部的な仕組みではなく、セッションのトランスクリプト上に1行のメッセージとして表示されるという設計だ。

"The watched session shows a line saying another process asked to be told when the session is next idle. The asking session shows the notice as a line naming the watched session. The line can include the time that session's turn finished and a one-line status from that turn."

（監視対象のセッションには、別のプロセスが「次にアイドルになったら知らせてほしい」と依頼してきた旨の1行が表示される。依頼した側のセッションには、監視対象セッションの名前を含む1行として通知が表示される。この行には、対象セッションのターンが終了した時刻と、そのターンの1行ステータスが含まれることがある）

「一回限り」という制約にも、具体的なタイムアウトが設定されていた。

"If no notice arrives within 12 hours, Claude Code drops the subscription and tells Claude, so it doesn't keep waiting."

（12時間以内に通知が届かない場合、Claude Codeは購読を打ち切り、Claudeにその旨を伝える。これにより、Claudeが延々と待ち続けることを防ぐ）

さらに、誰がこの機能を使えるかにも制限がある。「メインの会話にいるClaudeだけが購読でき、対象はこのマシン上の自分のセッションに限られる。サブエージェントやチームのメンバーがnotify_when_idleを設定しても、Claude Codeは購読せず、その旨を伝える。他のエージェント（チームメイト・サブエージェント・別マシン上のセッションなど）に通知を求めた場合、Claude Codeはメッセージごと呼び出し全体を拒否する」と明記されている。

refuse／hold設定でnotify_when_idleがどう変わるか

notify_when_idleの通知も、通常のクロスセッションメッセージと同じcrossSessionInboundという受信設定の対象になる、と公式ドキュメントに明記されている。

"Each side's inbound controls apply to a notice like a message: refuse on either side: nothing arrives. The watched session drops the request without recording or answering it, so the subscription expires unanswered after 12 hours, and an asking session with refuse never subscribes. hold on either side: the notice arrives with less. The watched session leaves the one-line status out, and the asking session shows the notice in your transcript without delivering it to Claude."

（訳：両側の受信設定は、通常のメッセージと同じように通知にも適用される。どちらかがrefuseの場合：何も届かない。監視対象セッションは記録も応答もせずに依頼を破棄するため、購読は応答のないまま12時間で期限切れになり、依頼する側がrefuse設定なら、そもそも購読自体が成立しない。どちらかがholdの場合：通知は情報が欠けた形で届く。監視対象セッションは1行ステータスを省略し、依頼した側はトランスクリプト上に通知は表示されるが、Claudeへは配信されない）

crossSessionInboundが取りうる値は3つで、公式ドキュメントの表は次の通り。

設定の優先順位についても、別ページ「Settings reference」に明記がある。「managed settings（管理者設定）→ --settingsフラグ → user settings（ユーザー設定）の順で読み、最初に見つかった値を適用する。refuseはholdより厳格で、holdはacceptより厳格」（原文: "refuse is stricter than hold, and hold is stricter than accept"）とされ、信頼できるソースのいずれにも値が無い場合でも、プロジェクト単位・ローカル単位でholdかrefuseが設定されていればそちらが優先される。つまり、当初「ドキュメントの説明をそのまま紹介したもので実際には試していない」としていた挙動は、notify_when_idle専用の記述として公式ドキュメントに明記されていることが確認できた——ただし、実機で複数セッションを立ち上げてこの通りに動くかどうかまでは、依然として自分の手元では検証していない。

同じマシン上の通信は、セッションごとに専用のソケット（またはWindowsでは名前付きパイプ）で行われるが、これを外部のスクリプトから直接叩くための仕組みも用意されている。環境変数を扱う別ページ（env-vars）によれば、受信箱ソケットを持つセッションでは、Claude CodeがCLAUDE_CODE_MESSAGING_TOKENというセッション固有のトークンをhooksやBashコマンドに自動でエクスポートしており、外部スクリプトがこのソケットに投稿する際、最初の行で{"type":"auth","token":"<token>"}という形式のトークンを送ることで、そのセッションに属することを証明できる、とされている（v2.1.228以降）。

SendMessage・ListAgentsまわりの他の改善

同じv2.1.236のリリースノートには、SendMessage関連の別の修正も含まれていました。

"SendMessage now refuses further messages to a session up front once a rapid burst would exceed what that session's inbox accepts, instead of reporting them sent while they were dropped"

（訳：SendMessageが、セッションの受信箱が受け付けられる量を超えるような急激なメッセージのバーストが起きた場合、事前に以降のメッセージ送信を拒否するようになった。以前は、実際にはドロップされているのに「送信済み」と報告されていた）

notify_when_idleと合わせて、クロスセッションメッセージング機能全体の信頼性・使い勝手を細かく改善している時期だったことがうかがえます。

Windows現状の扱いとrefuse/holdの挙動は自分の環境で試していない

• notify_when_idleが現在Windowsでも使えるのかどうかは、公式ドキュメントの記述だけでは断定できなかった。実際にWindows環境でクロスセッション通知を試す検証は行っていない
• 通知の到着に影響する「受信側のrefuse／hold設定」がどう挙動を変えるか（refuseなら通知自体が届かない、holdならステータス情報が省かれる、等）はドキュメントの説明をそのまま紹介したもので、自分の手元で実際に複数セッションを立ち上げて動作を確かめたわけではない
• 「12時間で購読が打ち切られる」というタイムアウトの秒数・実装の詳細（内部でどうカウントしているか）までは、ドキュメントの記載以上には踏み込んでいない

関連記事

• ANTHROPIC_DEFAULT_MODELとANTHROPIC_MODELは別物
• Claude Codeが自分でフィードバックの下書きを作るようになった