Saccade

io.github.Tavrinv0.2.1Updated Oct 6, 2026

Perceptual visual regression, image evidence inspection and bounded decision proposals.

VerifiedSTDIODesktop onlyDeveloper ToolsMedia & DesignData & Analytics

Overview

AI-generated overview

A local MCP server that lets an assistant inspect perceptual image-difference reports and bounded visual-regression evidence.

What it does
Saccade measures perceptual differences between image captures, locates them in measured regions, and checks them against thresholds and policies you declare. It writes offline HTML reports and versioned JSON, and the local MCP server reads registered capture roots and writes reports under a separate output root. Its tools cannot approve baselines; agents can inspect bounded results and follow recorded next actions. Related CLI workflows cover comparison, OCR text differences, image inspection, media analysis and performance evidence.
When to use it
Worth adding when a coding agent needs to verify visual changes against a baseline, review CI visual-regression output, or inspect image evidence without a baseline. It suits teams that already produce capture pairs and want an assistant to read the resulting reports rather than run the comparison itself.
Requirements
Runs as a local process over stdio, installed from Cargo with Rust 1.89 or newer. It needs registered capture roots and a separate output root. Default comparisons need no provider account or GPU; optional features add pinned model artifacts, ONNX Runtime, system libraries, or external ffmpeg and ffprobe. No authentication, environment variables or headers are declared.
Before you install
The server reads capture roots and writes reports to an output root, so point it at directories you intend to expose. Its tools cannot approve baselines; only a human can. Optional AI provider features are opt-in and require explicit authorization, dedicated credential files and call or spend caps, and several assist and routing features remain experimental and unqualified. Perceptual passes do not prove correctness or that a difference is invisible.

Installation

In SourceWeft

  1. Open Saccade in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[CI] [crates.io] [docs.rs] [License] [MSRV] MCP Registry: io.github.Tavrin/saccade

saccade

saccade is a visual and performance evidence tool for humans, CI and AI agents. It measures perceptual differences, locates them in measured regions (with optional advisory observations), and checks them against the thresholds and policies you declare. It writes offline HTML reports and versioned JSON. Performance conclusions require comparable captures, timing provenance and repeat evidence. Only a human can approve a baseline.

[Report with image differences and numbered hotspots]

Quickstart

sh
saccade demo --out saccade-demosaccade view saccade-demo

The demo exits 1 on purpose: it contains changed and missing captures. Open saccade-demo/report/index.html to see the result. The quickstart walkthrough has copyable examples for comparison, exact identity, configuration, evidence export and local review.

Use cases

Visual verification for coding agents

The local MCP server reads registered capture roots and writes reports under a separate output root. Its tools cannot approve baselines. Agents can inspect bounded results and follow recorded next actions.

sh
saccade mcp --root captures --out-root agent-reportssaccade compare captures/before captures/after --out agent-reports/change --json

See the agent guide and MCP and plugin setup.

CI visual regression

The local Playwright package provides toMatchSaccade and capture stabilization. A sweep groups page pairs and records capture failures as failures.

sh
node integrations/playwright/sweep.cjs sweep.json captures capture-options.jsonsaccade sweep compare sweep.json --captures captures/captures.json --out sweep-report --json

See the Playwright matcher, sweep and CI integration. Sweep needs the optional products feature.

Render and engine evidence

Declared spatial policies distinguish texture_noise_only from systematic_shift. Required-effect checks can fail on an empty footprint; capture layers restrict measurement scope and fixed-camera sequences measure temporal stability. Supply the policies and capture provenance with your inputs.

sh
saccade compare before after --config render-evidence.toml --out render-report --jsonsaccade experiment sequence before-frames after-frames --fixed-camera --out temporal-report --json

See rendering evidence and engine capture ingestion.

Image delivery tuning

Audit served formats and search declared encodings for a perceptual target. Local and URL-template adapters record bytes and content types and do not modify originals.

sh
saccade imgtune audit --urls images.txt --accept 'image/avif,image/webp,image/*' --out audit.json --jsonsaccade imgtune search tuning.json --out tuning-report.json --json

See image tuning. Enable products, plus imgtune-avif for AVIF.

Media analysis records

A media record keeps status and provenance for metadata, quality, fingerprints and optional model sections. Disabled or failed sections are recorded as such. The Python package and local HTTP API use the same analysis path.

sh
saccade analyze-media image.jpg --profile cpu-lite --output-size 1200x800 --jsonsaccade keyframes video.mp4 --out frames --json

See media analysis, Python and HTTP API. Python wheels are built in CI and are not on PyPI yet.

Single-image provenance and integrity

Inspect C2PA credentials, metadata and compression-history indicators without a baseline. Heuristics have stated limits and do not establish a real/fake verdict. GPS disclosure is opt-in; C2PA validation needs credentials.

sh
saccade inspect-image received.jpg --output-size 1600x900 --out inspection --jsonsaccade inspect-image received.png --hash-index hashes/saccade-hash.v1.json --out indexed-inspection --json

See single-image inspection.

General comparison

Pick registration, hashes, embedding similarity/search, OCR text differences, no-reference quality or document rasterization to fit the question. Model workflows require supplied pinned artifacts and the relevant features.

sh
saccade compare before.png after.png --align similarity --out aligned-report --jsonsaccade text before.png after.png --out text-report --jsonsaccade assess image.jpg --out quality-report --json

See choosing a comparison, registration, hashing, embeddings and search, OCR, quality and documents.

Performance evidence

Compare supplied timing sidecars using paired statistics and uncertainty intervals, or locate changes in a sequence. Saccade does not run the benchmark; missing or rejected provenance cannot qualify a speedup.

sh
saccade compare before after --out perf-report --jsonsaccade history onset --store history --json

See paired statistics, change points and identity/performance.

Install

Install with Rust 1.89 or newer:

sh
cargo install saccade --version 0.2.1 --lockedsaccade doctor --json

To build this checkout, use cargo install --locked --path crates/saccade. Release archives include checksums, licences and third-party notices. See release instructions.

Cargo featuresDefault?Purpose and requirements
compression, parallel, graphicsYesFLIP, compression scores, graphics and temporal measurements; CPU processing.
ai, evaluationYesProvider review adapters and evaluation; calls require explicit authorization and budgets.
workbench, mcpYesLocal report browsing and bounded agent tools.
assistNoExperimental explain, mask audit, visible-condition checks and batch advice.
productsNoSweep, image tuning, design-source and notifier adapters. Browser captures separately need Node.js and Playwright.
imgtune-avifNoAVIF encoding/decoding; system dav1d >=1.3.0 development library and pkg-config.
semantic-regions, embeddings, local-modelsNoPinned CPU model artifacts and dynamically loaded ONNX Runtime 1.22 (API 22). Runtime/model pulls are explicit provisioning operations; analysis never downloads them.
ocr, ocr-providerNoLocal PP-OCRv5 Latin with pinned models/runtime; separately opt-in hosted document OCR with spend/egress controls.
documents, credentialsNoSVG/PDF rasterization and offline C2PA validation.
media-httpNoBounded URL inputs for media analysis; network fetches require an explicit URL input.
local-vlm, vision-providersNoConfigured local/hosted vision adapters; observations remain advice.
geometry, dense-motion, prechecks, schemaNoMesh measurements, dense motion, experimental safety/accessibility checks and schema generation.

Video extraction invokes external ffmpeg and ffprobe; neither is bundled. See model/runtime provisioning and AVIF prerequisites. Default comparisons need no provider account or GPU. Add optional features with cargo install ... --features products,ocr, for example.

Metrics and algorithms

Each qualification covers only the recorded contract and evidence. A passing score does not prove correctness or that a difference is invisible.

Metric or algorithmQualification status and scope
Native decoded-sample identityExact equality contract; covers only supplied, complete pairs.
NVIDIA FLIP / HDR-FLIPReference-backed implementation; viewing conditions and HDR mapping must be declared.
SSIMULACRA2 / Butteraugli 0.9.3Reference checks recorded; perceptual targets are user policy. See implementation evidence.
ColorVideoVDP, numerical buffers, motion and mesh distancesDeclared display/unit/frame/camera contracts; fixture checks do not qualify a consumer renderer.
Registration; aHash/dHash/pHash; FAST/oriented-BRIEF matchingGenerated-fixture validation; match confidence is uncalibrated.
Embedding similarity and image/text retrievalPinned model/export provenance; retrieval calibration remains unqualified.
PP-OCRv5 Latin and positional text diffGenerated strict and typographic contracts reviewed; font-specific failures remain.
Blur, noise, blockiness, banding, clipping and forensic indicatorsDescriptive, content-dependent heuristics; no authenticity qualification.
Spatial classes, effect occupancy, layers and temporal tilesConstructed/fixture contracts; no general renderer or physical-effect qualification.
Paired Hodges–Lehmann estimates, bootstrap and change pointsConstructed statistical checks; actual timing requires independent qualified runs.
Safety/accessibility prechecksExperimental checks; no certification or formal compliance.
AI assist, Jev support and routing (Jev is a decision model from TypeSafe), blind-order handlingUnqualified in this release; experimental.
LPIPS, DISTS, MUSIQ; TrustMark payload decodingDeferred / unavailable; neural-only TrustMark inference does not decode payloads.

AI layer

AI observations are advisory. They cannot approve baselines, create exclusions, override deterministic failures, establish equality or qualify timing. Providers are opt-in, with source-root egress authorization, dedicated credential files and call/spend caps; image text and provider output are data, never instructions.

The release qualification attempt with a $15 cap stopped at the prerequisite check, before any provider request or spend. No frozen corpus with an observed immutable Gemini revision or exact-source heavy receipt was supplied. Explain, mask audit, visible-condition checks, blind orders, Jev support, deterministic cascade routing and optional Jev evidence routing all remain unqualified. Assist commands still require --experimental; Jev routing stays off by default. See assist workflows, qualification policy and the release guide.

Known limitations

  • OCR can misread œ in large serif text and omit dashes with some sans fonts; omitted characters and missing spaces before € remain errors.
  • Retrieval scores lack qualified calibration. Model/runtime smokes establish execution, not production accuracy or export parity.
  • GI occupancy uses supplied masks/layers as a proxy; it does not prove physical illumination, causality or correct rendering.
  • LPIPS, DISTS and MUSIQ remain deferred; TrustMark payload decoding is unavailable.
  • Captures define the evidence scope. Equal images do not establish application correctness, and perceptual passes do not establish native sample identity.
  • Performance conclusions need matched workload, clocks, warmup and repeat noise. Missing checks remain unknown; human approval records do not authenticate an operator.

Documentation and integrations

9 reproducible cases with commands, expected exits and measured output. Pages gallery.

License

MIT OR Apache-2.0, at your option. FLIP uses the BSD-3-Clause flip-rs port. See third-party notices; release archives also include generated dependency notices.

MCP Registry ownership: mcp-name: io.github.Tavrin/saccade

Source: README.md at commit 54ee1c3

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.1LatestOct 6, 2026