Skip to content
← Back to release · 2.1.310
New features / v2.1.310

Monitor tool on more platforms

CHANGELOG · original

Added the Monitor tool and plugin monitors on Bedrock, Vertex, and Foundry, and when telemetry or nonessential traffic is disabled; long foreground sleeps are now blocked there too
Open official changelog ↗

Documentation

Documentation excerpt

Monitor tool

The Monitor tool lets Claude watch something in the background and react when it changes, without pausing the conversation. Ask Claude to:

  • Tail a log file and flag errors as they appear
  • Poll a PR or CI job and report when its status changes
  • Watch a directory for file changes
  • Track output from any long-running script you point it at
  • Connect to a WebSocket feed and report each message as it arrives

For most watches, Claude writes a small script, runs it in the background, and receives each output line as it arrives. For a server that already pushes events, Claude can open a WebSocket instead of running a script.

You keep working in the same session and Claude interjects when an event arrives.

Every watch Claude starts has a deadline: 5 minutes by default, at most 30 minutes, and at most 10 minutes in a non-interactive run given a single prompt with -p.

At the deadline the watch ends. Claude gets one notice, so it can start the watch again if it's still needed.

Stop a monitor by asking Claude to cancel it or by ending the session. When you stop a subagent that started monitors, for example from /tasks, those monitors stop with it.

When Monitor runs a command, it uses the same permission rules as Bash, so allow and deny patterns you have set for Bash apply here too. While auto mode is active, Claude Code sets aside allow rules that name Monitor itself, along with the other broad allow rules it drops, so the classifier reviews Monitor commands the same way it reviews Bash commands.

Monitor needs a minimum version or Git Bash in these cases:

  • Minimum version: on Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, or Microsoft Foundry, or with DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, Monitor requires Claude Code v2.1.310 or later. The requirement applies when feature-flag fetching is off
  • Windows: the tool is available only when Git Bash is installed

Plugins can declare monitors that start automatically when the plugin is active, instead of asking Claude to start them. See plugin monitors.

WebSocket source

When a server already pushes events over a WebSocket, Claude can connect to it directly instead of writing a polling script. Each kind of socket activity either becomes an event or ends the watch:

  • Text messages: each one becomes one event, even when the message spans multiple lines.
  • Binary messages: not passed through. Claude receives a placeholder line such as [binary frame, 512 bytes] instead.
  • Messages larger than 1 MiB: the watch ends, so subscribe to a filtered feed where one exists.
  • Socket close: the watch ends and Claude receives the close code.

A WebSocket watch takes a ws input in place of command, and a single Monitor call can't combine the two. The ws input has two fields:

Field Required Description
url Yes The endpoint to connect to. Must be a ws:// or wss:// URL with no embedded credentials or whitespace, using ASCII characters only
protocols No WebSocket subprotocol names to offer during the handshake. Each entry must be a valid subprotocol token, and the list can't contain duplicates

The timeout_ms deadline applies to a WebSocket watch too: the watch ends at the deadline, and TaskStop cancels it early.

Without a Monitor allow rule, you're prompted before Claude opens a WebSocket; in auto mode the classifier decides instead, unless an ask rule applies. The prompt doesn't offer an option to skip future prompts for the same host.

Addresses and hosts denied to WebSocket watches

Claude Code denies URLs that point at a private, link-local, or cloud-metadata address, including hostnames that your machine resolves to one. Behind a proxy, a watch can reach a private, link-local, or cloud-metadata address unless the proxy blocks it, because Claude Code doesn't check the address the proxy finds. Claude Code also denies hosts in sandbox.network.deniedDomains, and when allowManagedDomainsOnly is set in managed settings, any host outside the managed allowlist.

If a watch behind a proxy fails with could not resolve <host>, restart Claude Code v2.1.319 or later with CLAUDE_CODE_PROXY_RESOLVES_HOSTS set to 1 so the proxy looks up the hostname.

Bash rules that deny or prompt for WebSocket watches

If Claude Code refuses a Monitor call that opens a WebSocket, look for a deny or ask rule written Bash or Bash(*). Do the same if it prompts for that call despite your Monitor allow rule. A rule on every Bash command also covers these WebSocket watches:

  • Deny rule: if the rule is in place when the session starts, Claude doesn't have the Monitor tool, so it can't start the watch. If you add the rule during a session, Claude's next Monitor call is refused. The refusal reads Permission to use Monitor has been denied: it runs code as Bash does, and a rule denies Bash.
  • Ask rule: you're asked to approve the watch. You can't have an allow rule, a PreToolUse hook, bypassPermissions mode, or the auto mode classifier approve it for you. You can approve it from a PermissionRequest hook. Where nobody can answer, such as in dontAsk mode, Claude Code denies the watch.

To let these watches run, narrow the rule to the commands you mean, such as Bash(rm *).

The ask rule, and a deny rule you add during a session, cover these watches in Claude Code v2.1.319 or later.

Documentation snapshot · 2026-11-20

Change details