Source: W15 release notes + Anthropic tools-reference + Noah Zweben (PM) tweet + claudefa.st + MindStudio deep-dives (ai-research/claude-code-monitor-tool-2026-05-09.md); behaviour changes from Claude Code v2.1.271, v2.1.274 and v2.1.284 release notes (ai-research/claude-code-release-v2-1-271.md, raw/anthropic-watch-claude-code-tag-v2-1-274.md, raw/anthropic-watch-claude-code-tag-v2-1-284.md)

Anthropic shipped the Monitor tool in Claude Code v2.1.98 on April 9 2026 as a built-in background watcher: it spawns a shell command, treats the command’s stdout as an event stream, and wakes Claude with a new transcript message every time the command emits a line. The architectural shift is from time-driven to event-driven — replacing the Bash sleep-loop polling pattern with proper interrupt-driven re-entry.

Key Takeaways

  • First-class Claude Code tool, not a Messages API primitive. Lives under code.claude.com/docs/en/tools-reference#monitor-tool. There is no equivalent in the Anthropic Messages API as of May 2026 — this is a harness feature available only inside Claude Code (CLI / Desktop / web).
  • Every watch has a deadline (since v2.1.271, 2026-09-14). A watch runs for at most 30 minutes — 10 in single-prompt -p runs — and then Claude is notified to re-arm it. This replaced the no-timeout persistent option. Long watches are now a chain of re-armed watches, not one session-long process.
  • Parameters: description (label shown on every notification) and command (shell script whose stdout is the event stream), plus a timeout. At launch the timeout was timeout_ms (default 5 min, max 1 hr) and a persistent flag ran the watch for the full session; see Changes since launch below for what replaced them.
  • stdout = events, silence = nothing to report. Each line of output wakes Claude with a transcript message. While the command is silent, Claude spends zero tokens.
  • Pairs with self-pacing /loop. When you run /loop without an interval, Claude either schedules ticks based on the task or reaches for Monitor instead — choosing event-driven over time-driven on its own.
  • Two stable patterns: stream-and-filter (tail -f log | grep ERROR, inotifywait, WebSocket emitter) and poll-and-if (cron-style script that emits only on condition change).
  • Token math is the headline win. Pre-Monitor pattern: a /loop 30s waiting on a 10-min build burned ~20 polling round-trips of context. Post-Monitor: zero round-trips while the build runs, one transcript message when it finishes or breaks.

How it differs from existing background mechanisms

MechanismSurfaceWakes Claude on output?Survives session end?Best for
Monitor tool (W15)Claude Code built-inYes — stdout events stream into the conversationNo (session-scoped; each watch ends within 30 min and Claude is told to re-arm — since v2.1.271)Live event sources, condition-changed polling, “tell me the moment X happens”
Bash(run_in_background=true)Claude Code Bash tool flagNo — output is buffered; Claude must poll with BashOutput to read itNoAsync commands where you’ll come back to read output later
/loop <interval> <prompt>Claude Code slash commandNo — re-runs prompt at intervals (re-issues the same prompt + tools)No (session-scoped)“Re-check this every N minutes while I work”
Routines / Scheduled TasksAnthropic platform primitiveIndependent agent run, not a wake eventYes (cron-driven, persists across sessions)Recurring time-based jobs, daily digests, weekly sweeps
cron / launchd / GitHub ActionsOperating system / CINo — no Claude session to wakeYesTime-based jobs that run without an active Claude session

The decision tree:

  • “I need Claude to react the moment X happens during this session” → Monitor
  • “I need to fire a command in the background and come read the output later” → Bash(run_in_background=true) + BashOutput poll
  • “I need to retry/check a thing every N minutes for the rest of this session” → /loop (which may itself reach for Monitor)
  • “I need a thing to happen on a schedule even when Claude isn’t running” → Routines or Scheduled Tasks / cron / GitHub Actions

Where Monitor replaces polling — concrete patterns

Tail-and-filter (stream-and-filter pattern):

# Watch application logs for errors
tail -f /var/log/app.log | grep --line-buffered "ERROR"
 
# Watch file system changes
inotifywait -m --format '%e %f' /watched/dir

Poll-and-if (the only legitimate sleep-loop pattern remaining — emit on change, not on schedule):

# Poll GitHub PR for new comments every 30 seconds
last=$(date -u +%Y-%m-%dT%H:%M:%SZ)
while true; do
  now=$(date -u +%Y-%m-%dT%H:%M:%SZ)
  gh api "repos/owner/repo/issues/123/comments?since=$last" \
    --jq '.[] | "\(.user.login): \(.body)"'
  last=$now; sleep 30
done

Conditional readiness signals (per MindStudio’s deep-dive):

“Start the dev server in the background. Monitor for the ‘ready’ message, then let me know when it’s accepting connections. Also alert me if it crashes.”

Timeout safety valves:

“Run the integration tests in the background. Monitor for completion. If they haven’t finished in 10 minutes, interrupt and report current status.”

Origin announcement (Noah Zweben, Claude Code PM)

“Claude can now follow logs for errors, poll PRs via script, and more. Big token saver and great way to move away from polling in the agent loop.” — @noahzweben, April 9 2026

Workflows where Monitor would replace polling

Three concrete patterns from this stack where Monitor cleanly replaces an existing sleep loop:

  1. Hermes self-improving loop — currently uses /loop 5m to check whether the latest training run produced a new model. Monitor on tail -f hermes/runs/*/results.jsonl | grep --line-buffered '"completed":true' would wake the agent the millisecond a run finishes instead of burning a poll every 5 minutes.
  2. GSC SEO Autonomous engine — currently polls Search Console for click-deltas every cron tick. The poll-and-if pattern (emit only when a tracked keyword crosses a threshold) directly maps to Monitor.
  3. Weekly wiki sweeps — already cron-scheduled (Friday + Sunday cloud routines). Monitor isn’t a fit here — sweeps run without an active Claude session, so Routines is the right primitive.

Implementation

Tool/Service: Claude Code built-in tool (since v2.1.98) Setup: No setup. Ship Claude Code v2.1.98+ and Claude can invoke the Monitor tool inline. Phrase prompts as “tell me the moment X” or “watch Y in the background” rather than “run X” so Claude reaches for Monitor instead of synchronous Bash. Cost: No incremental cost — token spend goes to zero while the watcher is silent. The cost win is everything you were spending on polling round-trips before. Integration notes:

  • The Monitor tool’s command parameter accepts any shell script. Pipe through grep --line-buffered (or equivalent) so per-line filtering doesn’t block on stdio buffering.
  • Deadlines (v2.1.271+). A watch lasts at most 30 minutes (10 in -p runs); when it expires Claude is notified to re-arm. Long-running watchers (full test suite, training run, all-day CI) therefore run as repeated re-arms. For a single -p run that must wait longer than 10 minutes, plan for re-arming or use a different primitive.
  • Before v2.1.271, persistent: true watches ran for the whole session and needed TaskStop to end. The v2.1.271 note does not say whether TaskStop behaviour changed.
  • Stop/start discipline. A monitor that emits a torrent of lines (e.g., a debug log on a hot path) will flood the conversation. Filter aggressively at the shell layer, not at the Claude layer.

Changes since launch

  • 2026-09-14 — v2.1.271: deadlines replace persistent. “Changed Monitor watches to always have a deadline (at most 30 minutes; 10 in single-prompt -p runs) and notify Claude to re-arm, replacing the no-timeout persistent option.” The same release added per-command allowed_domains for Bash, PowerShell and Monitor in auto mode with sandboxing: the hosts a command needs are reviewed with it and opened for it alone.
  • 2026-09-17 — v2.1.274: one notification at exit. A script’s final output and its exit now arrive as one notification instead of two, saving a model turn.
  • 2026-09-28 — v2.1.284: clearer event rows. Monitor event rows show what each event printed instead of repeating the description, and an unchanged “Waiting for N … to finish” line is no longer repeated after every event.
  • History (2026-04-09 → 2026-09-13): the tool launched with timeout_ms (default 5 min, max 1 hr) and a persistent flag that kept a watch alive for the full session until TaskStop.

See Week 38 and Week 40 for the surrounding releases.

Open Questions

  • Is timeout_ms still the parameter name, and is its maximum now 30 minutes? The v2.1.271 note gives the 30/10-minute ceiling and the re-arm behaviour but does not name the parameters.

  • Messages API parity. Will Monitor (or an equivalent event-driven primitive) ship in the Messages API for non-Claude-Code agent harnesses? Currently it is Claude Code-only.

  • Multiple concurrent monitors. The W15 docs are silent on the upper bound. Anecdotally, Anthropic’s example flow uses one or two; behavior with 10+ monitors fanning lines into the same conversation is undocumented.

  • Output buffering edge cases. tail -f | grep works because of --line-buffered; some commands buffer their own stdout block-wise (Python without -u, Node without process.stdout.uncork()). Monitor docs don’t enumerate the buffering pitfalls.

  • Token cost of high-frequency events. A monitor emitting 100 events per minute is essentially polling, just inverted. Where is the break-even?

  • Interaction with Routines. If a Routine spawns a Claude session that then opens a Monitor, who owns lifecycle? Routine-level vs session-level termination semantics not specified.

Try It

  1. Replace your noisiest /loop. Find the /loop 30s … you most regret. Rewrite as a Monitor invocation: “Watch dist/build.log for ‘compiled successfully’ and tell me when it lands. Alert me if ‘ERROR’ appears.”
  2. Babysit a PR with one prompt. > Tail the CI for PR #123 in the background. Tell me when checks turn green or red. Read the output of gh pr checks --watch is a good underlying command if you want to peek at the shape Claude generates.
  3. Wire dev-server crash detection. > Start the dev server in the background. Monitor for the 'ready' line, then let me know when it accepts connections. Alert me if it exits unexpectedly. This pattern is the W15 docs’ demo example.
  4. Compare token spend. Pre-Monitor, run a 10-minute task with /loop 30s status. Post-Monitor, run the same task with a Monitor invocation. /cost (W15 also shipped a per-model + cache-hit breakdown) tells you which approach won.
  5. Replace one Hermes/GSC poll. Identify one polling cron in the broader stack and rewrite as Monitor. Document token delta in the relevant runbook.
  • Week 15 (April 6-10) Release Digest — original changelog entry; this article is the deep-dive.
  • Claude Code CLI Reference — Bash tool, run_in_background flag, BashOutput.
  • Scheduled Tasks — pairs with Monitor + self-pacing /loop for the time-driven half of background work.
  • Claude Code Routines — cron-style harness primitive for jobs that run without an active Claude session.
  • Claude Code Hooks — different async surface; hooks fire on Claude Code lifecycle events, Monitor fires on external command output.
  • Agent Skills Overview — Monitor is built-in, not a skill, but the “model-invoked tool” pattern is shared with skills.
  • Claude Managed Agents — server-side runtime where the absence of a Monitor-equivalent shapes harness design.
  • Cost & Intelligence Levers — Monitor is the cleanest cost lever to land in 2026 — it directly removes polling round-trips from the spend curve.