visual-rubric
visual-rubric runs AI-assisted rubric checks against screenshots through
codex-acp. It is intended for local visual UX review loops where deterministic
tests can prove structure and screenshots can catch layout, hierarchy, and
readability regressions.
The crate exposes:
evaluate_image_rubric_with_optionsfor one-off screenshot checks.evaluate_image_rubric_with_configwhen callers need a customcodex-acpbinary, environment, or working directory.evaluate_image_sequence_rubric_with_optionsfor ordered interaction checkpoints; it bounds frame count and can require semantic before/after transition assessment.RubricPoolfor repeated checks with process reuse, retry backoff, quota detection, and worker recycling.BatchRubricRunfor caller-provided asset batches with changed-file selection, partial-error reports, ACP log capture, and optional issue classification hooks.visual-rubricCLI for image checks, local static hosting, screenshot capture, and advisory audit reports.
Feature flags:
fake-codex-acpbuilds thefake-codex-acptest helper binary. It is off by default and does not change the library API.
Project-specific judgment belongs in the caller-provided system_prompt; the
default prompt only covers generic screenshot breakage such as clipped text,
overlapping controls, blank regions, illegible contrast, and visibly broken
layout.
The same form is available as an explicit subcommand:
Ordered journeys are sent as one labelled multimodal request so the rubric can judge both the checkpoint states and the interaction between them:
The sequence policy defaults to eight frames with transition assessment enabled.
Home Manager/Infernix deployments emit the same policy under [sequence] in
~/.config/visual-rubric/config.toml; --max-frames can override the bound
for a local run, while --no-require-transition is intended only for a
single-state diagnostic.
For generated assets, callers can keep project-specific discovery downstream and let the crate own generic batch mechanics:
use ;
let stable_hash = ;
let before = capture?;
let after = capture?;
let changes = diff_snapshots;
let report = new
.run;
For local website iteration, serve a static directory, capture browser screenshots, and write a report:
Audit reports are versioned JSON. They include an aggregate status, capture URL,
elapsed time, effective high-level options, and one rubric result per screenshot.
Use --fail-on-rubric when CI should fail on rubric failures or rubric errors.
For a versioned browser matrix, capture keeps one Chromium session and writes
full-page/viewport images plus DOM, accessibility, readiness, console, and
deterministic layout evidence:
Use --fake-pass only when checking capture/report plumbing; it is not a
semantic visual verdict.
Calibration fixtures can then be checked without a model call:
The deterministic gate catches declared DOM/layout/runtime classes; it complements, rather than replaces, semantic screenshot review.
For Home Manager-managed setups, keep backend selection in
~/.config/visual-rubric/config.toml and run:
Set mode = "direct" for direct codex-acp screenshot review, or
mode = "pipeline" for Qwen3-VL extraction followed by ACP rubric scoring.
--mode direct and --mode pipeline override the TOML mode for one run.
For manual inspection without rubric evaluation:
The model must return strict JSON: