The problem it replaces
Waiting on a long-running Claude Code session used to mean one of two things: sitting there watching the terminal, or periodically switching back to check whether it had finished. Neither is great when the work genuinely takes a while, a large migration, a long test suite, a background research task. notify_when_idle, shipped in Claude Code v2.1.236 (19 August 2026), gives you a third option: ask the session doing the work to tell you the moment it's done, once, and then leave it alone until it does.
It's not a new tool. It's a new input on SendMessage, the same tool cross-session messaging already uses to pass text between your independent sessions, documented under Get a notice when another session goes idle in Claude Code's own reference.
How to actually use it
You don't call SendMessage yourself, and you don't need to know the notify_when_idle parameter exists to use the feature. Just describe what you're waiting on in plain language:
Tell me when the migration session finishes what it's working on
Claude handles the mechanics: it identifies the target session (by name, or by asking which one you mean if more than one matches), and subscribes using SendMessage's notify_when_idle input. Two ways that subscription can happen:
- Attached to a message Claude's already sending. Claude delivers the message first, and the idle notice arrives later, whenever the watched session actually goes idle.
- On its own, with no message attached. Claude Code subscribes without starting a turn or spending tokens in the watched session at all. If that session happens to already be idle at the moment you ask, the notice comes back right away.
What "idle" means here
A session counts as idle the moment it finishes a turn with nothing queued behind it, or when it exits entirely. That's a precise definition worth having straight: a session that's mid-turn, even one that's been running for a while on a single long tool call, hasn't gone idle yet. The notice fires on the transition from "working" to "nothing left to do," not on any fixed timer.
What each side sees
The watched session shows a line saying another process asked to be told when it next goes idle. It's visible, not a silent background subscription you'd have no way to notice from the other end.
The asking session shows the notice as a line naming the watched session, once it fires. Per Claude Code's documentation, that line can include the time the watched session's turn finished and a one-line status summarising what that turn actually did, so you're not just told "it's done," you get a sense of what happened. If your session is idle when the notice arrives, Claude Code starts a fresh turn with it, the same way an ordinary cross-session message would land.
Why it's not polling
The core design choice here is that neither session checks on the other repeatedly. Claude Code sends the notice exactly once, from the watched session's side, the moment the idle condition is met. There's no interval to tune, no repeated status-check turn burning tokens in either session while you wait. That's a meaningful difference from the alternative of asking a session "are you done yet?" on a loop, which is itself a request that costs tokens and adds noise every time it runs, whether or not anything's actually changed.
If the watched session never goes idle within 12 hours, Claude Code doesn't leave the subscription hanging indefinitely. It drops the subscription automatically and tells Claude, so nothing keeps waiting on a notice that's never coming, and Claude doesn't keep asking about it turn after turn under the mistaken impression a notice is still pending.
Who can subscribe, and to what
Two restrictions worth knowing before you rely on this:
- Only the Claude in your main conversation can subscribe, and only to your sessions on the same machine. If a subagent or an agent team teammate tries to set
notify_when_idle, Claude Code makes no subscription at all, and tells that subagent or teammate so, rather than quietly failing. - Asking for a notice from anything beyond a same-machine session is refused outright. If Claude tries to request a notice from a teammate, a subagent, or a session on another machine or the web, Claude Code refuses the whole call, including any message you'd attached to it, and reports the refusal back to Claude so it can resend just the message without the notice request.
That second restriction is a real constraint: notify_when_idle is specifically a same-machine, main-conversation-to-main-conversation feature. It doesn't extend to a session on another of your machines connected over Remote Control, or to a cloud session on Claude Code on the web, even though ordinary cross-session messages can reach both of those.
Inbound controls still apply
A notice isn't exempt from the same crossSessionInbound controls that govern any other cross-session message, on either side of the subscription:
| Setting | Effect on the notice |
|---|---|
refuse on the watched session | It drops the subscription request without recording or answering it; the request expires unanswered after 12 hours as if nothing had happened |
refuse on the asking session | It never subscribes in the first place |
hold on the watched session | The notice still arrives, but without the one-line status describing what the last turn did |
hold on the asking session | The notice shows up in your transcript, but Claude Code doesn't deliver it to Claude directly |
If you've locked down cross-session messaging generally, per the full guide to how sessions message each other, that same lockdown quietly covers notify_when_idle too. There's no separate setting to manage.
Availability
notify_when_idle inherits the same requirements as cross-session messaging generally: Claude Code v2.1.224 or later for the underlying messaging feature, plus v2.1.236 or later specifically for notify_when_idle itself. It's available on macOS, Linux (including inside WSL 2), and, since v2.1.234, native Windows. It isn't available on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry, and it's turned off if any of CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, DISABLE_TELEMETRY, DO_NOT_TRACK, or DISABLE_GROWTHBOOK disables the underlying feature-flag evaluation cross-session messaging depends on.
How it compares to Monitor and to polling with a message
Claude Code already had two other ways to react to something without you watching it directly, and it's worth knowing where notify_when_idle fits against both.
The Monitor tool watches something external to Claude Code entirely, a log file, a CI job's status endpoint, a directory, a WebSocket feed, and interjects when that external thing changes. notify_when_idle watches the internal state of one of your own Claude Code sessions instead, specifically whether it's finished a turn with nothing queued. They're not substitutes: Monitor is for reacting to the world outside Claude Code, notify_when_idle is for reacting to another one of your own sessions.
The other alternative is simply asking, over and over, "is the other session done yet?" That's the polling approach notify_when_idle exists to avoid. Every repeated check costs tokens in the asking session and adds a turn to the watched one if it involves messaging it directly, whether or not anything has actually changed since the last check. A one-shot subscription instead costs nothing further until the actual event, going idle, has happened.
| What it watches | Repeats? | Costs tokens while waiting | |
|---|---|---|---|
notify_when_idle | Another of your sessions, same machine | No, one-shot | No |
| Monitor | An external log, job, file, or WebSocket feed | Continuously, but event-driven, not polling | Only when an event fires |
| Manually re-asking on a timer | Whatever you ask about | Yes, every interval | Yes, every check |
A worked example
Say you're running a large refactor in one terminal and want to keep working on something unrelated in another, without repeatedly Alt-tabbing over to check progress. In the second session:
Let me know the moment the refactor session in the other terminal goes idle
Claude subscribes on your behalf, spending nothing in the watched session beyond the subscription itself. You keep working. Whenever that refactor session finishes its current turn with nothing left queued, or if it's already sitting idle the moment you ask, Claude Code delivers a single notice back, with a short status line describing what that last turn actually did, so you know not just that it's done but roughly what it did on its way there.
Pairing it with background sessions
notify_when_idle is especially useful alongside background sessions, the ones you dispatch work to and let run without a terminal attached. A background session is exactly the kind of thing you'd otherwise check on repeatedly out of habit, since there's no visible prompt sitting there to remind you it's still working. Asking your main session to watch a dispatched background session closes that gap: you keep working in the foreground, and the moment the background work actually finishes, you get told, without either session spending anything in between.
This composes naturally with how ListAgents already surfaces background sessions in its listing, marked bg so you can tell them apart from ordinary foreground sessions at a glance. You don't need to look the session up yourself first; describing what you're waiting on by name or by what it's doing is enough for Claude to find it and subscribe.
Troubleshooting
The notice never arrived. Check whether either session has crossSessionInbound set to refuse, which drops the subscription request or the notice silently from that side. If more than 12 hours have passed since you asked, the subscription has likely already expired on its own; ask again.
I got the notice but no status summary. The watched session's crossSessionInbound is probably set to hold. A held notice still arrives, but Claude Code leaves the one-line status out under that setting.
A subagent or teammate says it can't set this. That's expected, not a bug. Only your main conversation's Claude can subscribe to a notify_when_idle notice, and only for sessions on the same machine. A subagent or teammate that tries gets told plainly that no subscription was made.
I wanted a notice from a session on another machine or the web. That's outside what notify_when_idle supports. It's restricted to same-machine, main-conversation targets; for anything beyond this machine, an ordinary cross-session message, or checking in through Remote Control, is the available path instead.
Where to go next
For the full mechanics of cross-session messaging generally, discovery with ListAgents, delivery, and inbound controls, see how Claude Code sessions message each other. For watching something external rather than another of your own sessions, a log file, a CI job, a WebSocket feed, see what Claude Code's Monitor tool does. Browse the current Claude Code catalogue at getclaudeskills.com/platforms/claude-code.
Verified 22 August 2026 directly against Claude Code's own cross-session messaging documentation at code.claude.com, including the notify_when_idle section and the inbound controls it inherits.
