Pir MCP server

pir-mcp

A motion sensor for AI agents.

"Gives your LLM agents enough info to be a helpful "watcher" without being a privacy nightmare like Windows Recall" -Solteris-Dev

A PIR sensor tells you that something moved, never what. This is the same idea for a screen: an MCP server that watches named rectangles and answers "did this change?" and "has this gone still?" with a number, a size and a timestamp. No tool in it returns pixels, image files, or anything that could be turned back into a picture.

It exists because an agent driving a desktop keeps needing the same two things: wake me when the build output moves and tell me if this status bar has stopped ticking. Both are motion questions. Neither needs a screenshot.

What it does

the way a regional screenshot works (slurp, slop). The human chooses what is sensed; the agent gets the geometry. Use this whenever someone is there.

• pirpickregion ask the person at the screen to draw the rectangle,

(a clock, a spinner, a caret).

• pirpickmask the same gesture for a patch inside a region to ignore

layout coordinates, with optional masks.

• pirdefineregion the scriptable path: name a rectangle by global

fixed rectangle. Its geometry is looked up again before every capture, so the region follows the window when it moves; a resize counts as maximal change. The pick offers your visible windows as boxes to click.

• pirpickwindow / pirdefinewindow watch a window instead of a

region. Cheap; also the way to check the capture command works.

• pirsample** capture once, score against the previous sample of that

when the call began, or time out. A doorbell.

• pirwaitforchange** block until the region departs from how it looked

stillforms, or time out. A short window means "the animation settled, safe to act". A long window on something that should keep changing means it is frozen, and still=true is the alarm.

• pirwaitforstillness** block until nothing has changed for

• pirlistregions, pirremoveregion housekeeping.

Every comparison reports two numbers over a coarse grid of averaged colour cells (at most 64 across, each at least 4 px), both 0 for identical and 1 for black against white:

edge or an antialiased caret scores about 0.02; a dialog opening 0.1 or more. This is the default metric, threshold 0.05.

• rmse over the whole grid: did the region as a whole move? A cursor

digit flipping inside a 1920-wide status bar scores rmse 0.018 (invisible to the default) but peak 0.145. Use metric=peak for a small thing that should tick inside a larger region.

• peak the single most-changed cell: did anything in it move? A clock

Averaging is what makes this a sensor rather than a camera: 64 cells cannot be read.

What it deliberately does not do

If an agent needs to see, use the screenshot tool your environment already has, so that choice stays explicit and yours.

• It never returns image data. There is no snapshot tool and none is planned.

milliseconds it takes to reduce it to a grid, and only the grid of the last sample is kept per region.

• It never writes frames to disk. A capture lives in memory for the

visible in the transcript, and pirpickregion carries a purpose line the agent has to write down before you draw.

• It does not capture on its own. Every sample is a tool call the agent made,

What it does reveal, so you can decide whether that is acceptable: that a given rectangle changed, at a given time, by a given magnitude. On a region covering a chat window that is presence information. Choose regions accordingly; the server has no opinion.

Shortened. The full README is on GitHub.