Capture a screenshot of the screen, a region, or a specific window.

On macOS, this uses the native screencapture command. On other systems, it uses PIL's ImageGrab or pyautogui as fallback.

For window capture on macOS, you need the numeric window ID (not the window name). You can find window IDs using: osascript -e 'tell app "System Events" to get id of windows of processes'

Load an existing image file for annotation.

Draw a rectangle/box on the image.

Draw a line on the image.

Draw an arrow on the image.

Add text annotation to the image.

Draw a circle on the image.

Add a semi-transparent highlight region to the image.

Pixel-perfect annotation tool. Places annotations at EXACT pixel coordinates. No anchor adjustments, no auto-positioning - pure pixel placement.

Coordinates:

• x, y: Top-left corner for box, center for circle, start for text

• x2, y2: End point for arrows/lines

Examples:

• precise_annotate(img, "box", x=100, y=200, width=150, height=50)

• precise_annotate(img, "text", x=100, y=180, text="Label")

• precise_annotate(img, "arrow", x=50, y=100, x2=200, y2=100)

• precise_annotate(img, "circle", x=300, y=300, radius=40)

Smart unified annotation tool with flexible positioning and anchor support.

Position formats:

• Named: "top-left", "center", "bottom-right", "top-left-quarter", etc.

• Percentage: "50%, 30%" (from top-left corner)

• Pixels: "100px, 200px" or "100, 200" (absolute x, y)

Anchor controls which part of the annotation aligns to the position:

• "top-left": annotation's top-left corner at position

• "center": annotation's center at position (default)

• "bottom-right": annotation's bottom-right corner at position

Offset allows fine-tuning: offset_x=10 moves 10px right, offset_y=-5 moves 5px up.

Examples:

• annotate(img, "box", "50%,10%", width=200, height=50, anchor="top-center")

• annotate(img, "text", "100px,50px", text="Label", anchor="top-left", offset_x=5)

• annotate(img, "callout", "center", text="Note", offset_y=-20)

Apply multiple annotations in a single call.

Pass a JSON array of annotation specs. Each annotation follows the same format as the annotate() tool.

Example: [ {"type": "box", "position": "top-left", "width": 200, "height": 100, "color": "blue"}, {"type": "text", "position": "top-left", "text": "Header Area"}, {"type": "arrow", "position": "center-left", "end_position": "center-right", "color": "green"}, {"type": "callout", "position": "bottom-right", "text": "Click here"} ]

Quickly label multiple regions of an image.

Pass a JSON object mapping region names to positions.

Example: { "Navigation": "top-left", "Search Bar": "top-center", "User Menu": "top-right", "Sidebar": "center-left", "Main Content": "center", "Footer": "bottom-center" }

Add a numbered step annotation with callout circle, arrow, and optional text.

This is a composite tool that combines a numbered callout with an arrow pointing to a target location. Useful for creating step-by-step tutorials or highlighting UI elements.

If callout_position is not specified, it's automatically placed offset from the target.

Blur or pixelate a region of the image to hide sensitive information.

Use this for hiding passwords, email addresses, personal info, etc.

Crop the image to a specific region.

Resize the image by dimensions or scale factor.

Add a numbered callout (circled number) to the image.

Numbers auto-increment if not specified, making it easy to add sequential callouts.

Reset the auto-increment callout counter to 0.

Add a border around the entire image.

Undo the last annotation on an image.

Get the number of available undo operations for an image.

Quick save to common locations (Desktop, Downloads, Documents, or temp).

Automatically determines the correct path based on the operating system.

Rotate the image by 90, 180, or 270 degrees.

Flip the image horizontally (mirror) or vertically.

Add a text watermark to the image.

Adjust image brightness.

Adjust image contrast.

Compare two images and optionally create a diff image highlighting differences.

Returns the percentage of pixels that differ and creates a new image showing the differences if highlight_differences is True.

Useful for comparing before/after screenshots, detecting UI changes, or validating visual regression tests.

Create a side-by-side comparison image from two images.

Useful for visual comparisons, before/after documentation, or A/B testing screenshots. Labels are added above each image if label_height > 0.

List all images stored in the current session.

Get current memory usage statistics for the image store.

Configure memory limits for the image store. Triggers eviction if new limits are lower.

Get a specific image by its ID. Returns the image data.

Create a copy of an existing image.

Delete an image from the session.

Export all images and metadata to a zip archive for later restoration.

The archive contains:

• All images as PNG files

• A manifest.json with image IDs, dimensions, and order

• Optionally, undo history for each image

Use import_session to restore the session later.

Import a previously exported session from a zip archive.

By default, merges with the existing session. Set merge=False to replace all current images with the imported ones.

Save an image to disk.

Copy an image to the system clipboard.

Get an image as a base64-encoded string.

Open an image in the native Preview app (macOS only).

On macOS, this opens the image in Preview.app for viewing and native annotation. On other platforms, it opens with the default image viewer.

Open an image file directly in the native Preview app (macOS) or default viewer.

This doesn't require loading the image into the session first.