Blog · November 6, 2026 · 7 min read · by Vilva Athiban P B

Claude Code's Monitor Tool: Watch Logs, CI Runs and PRs (Even a WebSocket) and Let Claude React While You Keep Working

You push a branch, CI starts, and you want to work on the next thing while someone keeps an eye on the checks. Claude Code’s Monitor tool, described on the Tools reference page as of 6 November 2026, makes that someone Claude: it starts a watch in the background, every line the watch prints comes back to Claude as an event, and Claude interjects when something happens. This post covers what the tool does, how it differs from background tasks and notifications, five watches to ask for, deadlines, permissions, the WebSocket source, plugin monitors, and the limits.

What the Monitor tool is

The docs put it in one sentence: Monitor lets Claude watch something in the background and react when it changes, without pausing the conversation. The listed uses are 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, and connect to a WebSocket feed and report each message. 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, it opens a WebSocket instead. You keep working in the same session.

Monitor vs background task vs notification

Three features sound alike and do different jobs. A background task is fire and forget: Claude starts a long command, you both move on, and /tasks is where you list background tasks and stop one. A background session is a separate Claude run doing its own work. If what you wanted from a “claude code background agent” was Claude reacting to events as they happen, Monitor is the closer match: it is not Claude working in the background, it is Claude listening to the background. A notification, covered in the notifications guide and this post, points the other way: it tells you that Claude is done or needs permission. Monitor tells Claude.

Five watches to ask for

You do not write the script; Claude does. You describe what to watch, what counts as an event, and when to stop. The filtering is deliberate; the trade-offs section explains why.

# 1. CI on the current PR
Watch the checks on this PR with gh pr checks (or gh run watch)
and tell me the moment one goes red, with the first error.

# 2. A dev server log
Tail ./logs/dev.log and interrupt me the first time you see
ECONNREFUSED. Ignore everything else. Stop the watch after that.

# 3. A build output directory
Watch ./dist for file changes and tell me when a new bundle
is written, with its size.

# 4. A long-running script
Run scripts/backfill.sh and report only lines containing ERROR
or the final "done" line.

# 5. A WebSocket feed
Connect to wss://events.example.com/deploys and summarise each
message in one line as it arrives.

For the first four, Claude writes and runs a script. For the fifth it opens the socket directly with the ws input below.

Deadlines: five minutes by default, thirty at most

Every watch 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 and Claude gets one notice, so it can start the watch again if still needed. If a CI run takes twenty minutes, say “watch for up to 30 minutes” up front and save a re-arm. To stop a watch early, ask Claude to cancel it or end the session. The “claude kill background task” move for a watch a subagent started is to stop that subagent, for example from /tasks, and its monitors stop with it.

Permissions: the Bash rules apply

When Monitor runs a command it uses the same permission rules as Bash, so your Bash allow and deny patterns apply to Monitor commands too. In auto mode, 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 way it reviews Bash commands. Opening a WebSocket has its own approval prompt, which the classifier also decides in auto mode. Two changelog notes: 2.1.290 (5 October 2026) fixed sandboxed Monitor commands skipping the permission prompt under sandbox auto-allow, and on Linux and WSL the CLAUDE_CODE_TOOL_MEMORY_LIMIT cap counts Monitor commands alongside Bash and PowerShell from v2.1.246.

The WebSocket source and its limits

A WebSocket watch takes a ws input in place of command, and one call cannot combine the two. The input has a required url (ws:// or wss://, ASCII only, no embedded credentials) and an optional protocols list of subprotocols to offer. Each text message becomes one event, even when multi-line. Binary messages are not passed through; Claude gets a placeholder such as [binary frame, 512 bytes]. A message over 1 MiB ends the watch, so subscribe to a filtered feed where one exists, and a socket close ends the watch with the close code. timeout_ms applies here too. The approval prompt offers no way to skip future prompts for the same host, and Claude Code denies private, link-local and cloud-metadata addresses (including hostnames that resolve to one), hosts in sandbox.network.deniedDomains, and, under allowManagedDomainsOnly, any host outside the managed allowlist.

Plugin monitors: watches that start with the session

A plugin can declare monitors that start automatically when the plugin is active, instead of asking Claude to start them. They live in a monitors/monitors.json file like this one.

[
  {
    "name": "error-log",
    "command": "tail -F ./logs/error.log",
    "description": "Application error log"
  }
]

The command runs in a shell in the session’s working directory, with your full user permissions and outside the sandbox, and what it prints reaches Claude as notifications. Plugin monitors start only in interactive sessions, never with -p. The command gets path variables and ${ENV_VAR} but never ${user_config.*} (a monitor that references one does not start). Disabling a plugin mid-session does not stop monitors already running. The experimental.monitors manifest key takes the same array inline or a path to a JSON file, and a when trigger can hold a monitor back until the first time a named skill runs.

Availability, and a docs page that may lag

The Tools reference says the tool is not available on Amazon Bedrock, Google Cloud’s Agent Platform or Microsoft Foundry, not when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set, and on Windows only with Git Bash installed. The changelog, however, lists “Monitor tool and plugin monitors on Bedrock, Vertex, and Foundry” as added in 2.1.310 on 23 October 2026, so treat the platform restriction as lifted from that version and the reference page as lagging. The telemetry and Git Bash conditions are unchanged there. The newest release as of writing is 2.1.311.

Where AI Done Now fits

The two tools point in opposite directions and compose. Monitor tells Claude that CI went red; Claude reads the log, proposes a fix, and then finishes or stops at a permission prompt. That moment is the one you wanted a “claude code notification when done” for, and it is what AI Done Now watches. Claude watches the pipeline; the app watches Claude.

Honest trade-offs

  • The five-minute default. A long CI job outlives the default watch. Ask for up to 30 minutes, and expect to re-arm after the deadline notice for anything longer.
  • A chatty log floods the conversation. Every event is a line Claude reads, and every line costs context tokens. Tell Claude what to filter for rather than tailing a firehose.
  • Not available with telemetry off or non-essential traffic disabled.
  • Plugin monitors run unsandboxed with full user permissions. Read a plugin’s monitors.json before enabling it.
  • Sometimes a background task is enough. No per-line reaction needed? A plain background task is cheaper.

FAQ

How do I stop a watch?

Ask Claude to cancel it, or end the session. If a subagent started it, stopping that subagent stops its monitors. TaskStop cancels a WebSocket watch before its deadline.

Does it work in headless -p runs?

Watches Claude starts do, with a 10-minute maximum. Plugin monitors never start in a -p run.

Can I use it on Bedrock, Vertex or Foundry?

The 2.1.310 changelog says yes; the Tools reference still says no. Update to 2.1.310 or later and try it.

Keep reading

Desk Exercises for Programmers: 15 Moves to Do While Your AI Agent Codes

7 min read

Exercise While Coding: Turn Claude Code Wait Time Into Micro-Workouts

7 min read

Claude Code Notch Notifications on Mac: See When Claude Is Done Without Watching the Terminal

7 min read

Claude Code Tips and Tricks: 12 Ways to Use Claude Code Effectively

8 min read

Claude Code Multiple Sessions: How to Run Agents in Parallel Without Losing Track

6 min read

A Claude Code Workflow That Doesn't Involve Watching the Terminal

5 min read

Claude Code Hooks: A Practical Guide to Automating Your Agent Workflow

7 min read

Claude Code Auto Mode: Fewer Permission Prompts Without Living Dangerously

7 min read

Claude Code Subagents: How to Delegate Work to Specialized Agents

7 min read

Claude Code Context Management: Treat the Context Window Like a Budget

6 min read

Per-Subagent Model Selection: Route the Grunt Work Down, Keep the Judgment Up Top

7 min read

Skills and Plugins: How to Teach Claude Code Your Way of Working

7 min read

Claude Code Background Tasks: Run Long Commands Without Blocking Your Session

6 min read

Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

7 min read

Cursor Notification When Done: Every Way to Get Notified When Cursor Finishes

6 min read

Claude Code Notifications: How to Get Notified When Claude Code Finishes or Needs Your Input

6 min read

Want to Be Notified When Claude Responds? How Claude Notifications Work on Web, Desktop, and Mobile

5 min read

Claude Code Notification Scripts: Copy-Paste Recipes for Every Platform

6 min read

Get a Ding the Moment Codex Needs Your Response

6 min read

Get Notified the Moment Claude Code Is Waiting for Your Input

6 min read

“Notifications Are Turned Off for Claude” — Here Is the Fix

6 min read

Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

6 min read

terminal-notifier + Claude Code: Native macOS Alerts When Your Agent Finishes

6 min read

Gemini CLI Notifications: How to Get a Sound or Alert When Gemini Finishes

6 min read

Get Claude Code Notifications on Your Phone

6 min read

Claude Code Remote Control, Explained

7 min read

preferredNotifChannel: Claude Code's Built-In Notification Setting

6 min read

Claude Code Notifications in tmux and Over SSH

7 min read

Claude Code Effort Levels: Why Your Setting Keeps Getting Ignored

8 min read

Codex vs Claude Code Notifications: How Each One Tells You It Is Done

8 min read

Claude Code Notifications Not Working: A Diagnostic Checklist

10 min read

Claude Code Notifications Inside Your Editor's Terminal

7 min read

CLAUDE_CODE_DISABLE_BACKGROUND_TASKS Explained

7 min read

CLAUDE_CODE_DISABLE_BG_SHELL_PRESSURE_REAP Explained

8 min read

Cursor Alerts Explained: Every Alert Cursor Raises, and How to Control Them

7 min read

Claude Code Environment Variables: The Groups That Actually Matter

10 min read

Claude Code Notifications on WSL and Windows

9 min read

Claude Code Checkpoints and /rewind

8 min read

Claude Remote Control: How It Works, Turning It Off, and Auto Mode

7 min read

Claude Code /loop: Poll a Deploy, Babysit a PR, and Get Told When It's Done

8 min read

Setting Up NotchFit With OpenAI Codex CLI: Hooks, $notchfit-plan, and the Daily Flow

7 min read

Claude Mods Explained: What the New Plugin Layer Can Do, and How to Turn On 'You Should Know'

9 min read

NotchFit vs Mac Break Reminder Apps: A Clock or a Signal From Your Coding Agent?

8 min read

Claude Code Headless Mode: Running claude -p in Scripts and CI, and the Three Signals That It Finished

10 min read

Building a Movement Habit at a Desk: Use the Agent Run as the Cue, One Set as the Unit, and Streaks Carefully

8 min read

Claude Code MCP Servers Explained: Adding Servers, Choosing a Scope, Handling Secrets, and Why Long Tool Calls Go to the Background

10 min read

/notchfit:plan Explained: How Claude Code or Codex Writes a Weekly Workout Plan the Notch Can Actually Run

8 min read

Claude Code Spinner Verbs Explained: What “Pondering” and “Brewing” Mean, How to Change Them, and Why You Should Stop Watching the Spinner

7 min read

Why NotchFit's Done and Permission Alerts Wait Until Your Set Ends, When That Costs You, and How to Turn the Workout Off

7 min read

How to Resume a Claude Code Session: --continue vs --resume, Naming Sessions, the Session Picker, Branching, and What Comes Back

9 min read

NotchFit on a Mac Without a Notch: How Pill Mode Works on Mac mini, iMac, Mac Studio and a MacBook With the Lid Closed

6 min read

How to Run a Claude Code Session in the Background: /background, claude --bg, Agent View, and Getting Back to It

9 min read

What a Notch App Can See: NotchFit's Local-First Design, What the Claude Code and Codex Hooks Send, and What Stays on Your Mac

7 min read

Why Codex CLI Asks for Permission Every Time, and How to Tune the Sandbox and Approval Policy Without Going Full Access

8 min read

What to Do While Claude Code or Codex Works: A Simple Protocol for the Two-to-Twenty-Minute Gap in Every Agent Run

7 min read

Is It Possible to Get a Notification When Claude Code or Codex Hits a Reset? Yes for Claude Code: the quota_auto_resume Hooks, Explained

8 min read

What a MacBook Notch App Can Actually Do: The Five Kinds of Notch Utility, Their Trade-offs, and Where NotchFit Fits

7 min read

How to Make MCP Servers Not Take Up as Much Context in Claude Code: Tool Search, alwaysLoad, Scopes and Output Caps

8 min read

The notchfit Command Line: Drive Your Workout, Read Status as JSON, Validate Plans and Test the Notch Without Leaving the Terminal

7 min read

How to Audit MCP Tool Calls Made by Claude Code: A Five-Minute Hook Audit Log, OpenTelemetry Tool Events, and the Transcript for Investigations

9 min read

Exercise Snacks: What the Research Actually Says About One-Minute Vigorous Breaks, What It Does Not, and How NotchFit's Agent-Run Sets Compare

8 min read

How Long Until a Claude Code MCP Tool Call Times Out? The Four Timers (Startup, Two-Minute Backgrounding, Idle, Wall-Clock), Their Defaults, and Which One to Change

8 min read

Sitting Too Long as a Developer: The Posture Problems Coding Agents Made Worse, What the Research Says About Breaking Up Sitting, and How NotchFit Turns an Agent Run Into the Break

8 min read

Claude Code .mcp.json Explained: Where Project-Scoped MCP Servers Are Read From, What Happens in Subfolders and Monorepos, and Why a Committed Server Shows Pending Approval

8 min read

Standing Desk Exercises for Developers: Why Standing Still Is Not the Goal, Eight Movements That Fit a Thirty-Second Agent Run, and How NotchFit Cues Them From the Notch

8 min read

The claude mcp Command Reference: add Syntax by Transport, What --scope local, project and user Actually Mean, add-json and add-from-claude-desktop, list, get, remove, login and serve

9 min read

Your First Week With NotchFit: Install and Simulate, Run Real Tasks, Write a Smaller Plan Than You Want, Tune the Alerts, Survive the First Skipped Day, and Decide What Stays

8 min read

How to Stop a Running Claude Code Task: Esc vs Ctrl+C, Background Tasks, Subagents, and Disconnecting Remote Control

8 min read

Pomodoro vs Agent-Driven Breaks: Timing Movement to Claude Code and Codex Runs Instead of a Timer

7 min read

Claude Desktop MCP Configuration: claude_desktop_config.json, Logs, Extensions, and the Difference From Claude Code

9 min read

The 20-20-20 Rule for Developers: Eye Strain, the Evidence, and Agent Runs as the Cue

8 min read

Claude Agent SDK + MCP Servers: mcpServers, allowedTools, Status Checks and Auth

9 min read

Discreet Desk Exercises for an Open-Plan Office While Claude Code Runs

7 min read

claude remote-control Server Mode: Run Claude Code as a Session Server

9 min read

Wrist and Forearm Stretches for Developers: A 60-Second Routine for Every Claude Code Run

7 min read

Claude Remote Control vs Claude Code on the Web: Which to Use and How They Differ

9 min read

Neck and Shoulder Stretches for Developers: A 90-Second Routine Between Agent Runs

7 min read

What Happens When You Step Away From a Claude Code Session: Prompt Cache Expiry, Idle Compaction, and When to Come Back

8 min read

Hip Flexor and Lower Back Stretches for Developers: A Two-Minute Standing Routine Between Agent Runs

7 min read

Hunched Over the Keyboard? Upper-Back (Thoracic) Stretches for Developers: A Two-Minute Seated Routine Between Agent Runs

6 min read

Claude Code Ultrareview: The 15–25 Minute Cloud Review, What to Do While It Runs, and How the Findings Come Back

8 min read

Why Your Legs Go Dead After a Long Claude Code Session: A Two-Minute Standing Calf, Glute and Hamstring Routine Between Agent Runs

7 min read

claude --teleport: Pull a Cloud Session Into Your Terminal, Start One With --cloud, Send Follow-Ups From the CLI, and the Requirements That Trip People Up

8 min read

Rounded Shoulders From Typing? A Two-Minute Chest Opener, Chair Twist and Wall Press Desk Routine for Developers Between Agent Runs

7 min read

Claude Code ultrathink Explained: It Now Runs the Turn at xhigh Effort, How It Differs From /effort, What It Costs in Time, and What to Do While It Runs

7 min read

Best Break Reminder Apps for Mac in 2026: Time Out, Stretchly, BreakTimer, LookAway and NotchFit Compared

7 min read

Claude Code 2.1.319: denyInsteadOfPrompting, MCP Background Tasks and What Changes for Unattended Runs and Notifications

8 min read

Drink Water and Stand Up Cues for Developers: Use Claude Code Agent Runs as Hydration and Standing Reminders

7 min read

Claude Code 2.1.323: Code Mode, Progress Heartbeat, Auto-Mode Fallback and 1M Context — What Changed for Unattended Runs

9 min read

Notch Media Controls on a Mac: What the MacBook Notch Can and Cannot Do, Dynamic Island-Style Apps vs NotchFit

7 min read