How Visual Verification Works for UI Changes in the Omarchy Development Workflow

Omarchy mandates that developers manually verify every UI change by capturing reference and candidate screenshots or videos using the omarchy capture suite, then comparing them in situ to catch visual regressions before committing code.

In the basecamp/omarchy repository, visual changes are treated as first-class citizens. Every modification affecting shell styling, layout, panels, menus, notifications, or animations requires explicit human validation through a structured workflow defined in agents/skills/visual-verification.md. This process ensures that subtle issues—such as clipping, overlap, stale state, or focus problems—are caught before they reach production.

The Three-Step Visual Verification Protocol

The workflow codified in agents/skills/visual-verification.md requires three mandatory steps for any code edit that touches on-screen elements.

1. Capture Reference Media

Before applying changes, document the current UI state. This establishes the baseline for comparison and must include the full context of the feature being modified.

2. Apply the Code Change

Edit the relevant source files—whether QML files for layout, CSS variables for theming, or panel definitions—and prepare the running environment to reflect the updates.

3. Capture and Compare the Candidate

Take a new screenshot or recording of the updated UI and compare it directly against the reference. Inspect for visual artifacts, spacing regressions, and incorrect state. Only after this side-by-side review is the change considered complete.

Capturing Screenshots and Screen Recordings

Omarchy provides dedicated CLI utilities implemented in bin/omarchy-capture-screenshot and bin/omarchy-capture-screenrecording to document UI state.

Full-Screen Screenshots

Use the omarchy capture screenshot fullscreen save command to write a timestamped PNG directly to the configured Pictures folder:

# Capture reference before making changes

omarchy capture screenshot fullscreen save

# → ~/Pictures/2024-08-19-screenshot.png

# Edit your QML, CSS, or panel configuration...

# Capture candidate after changes

omarchy capture screenshot fullscreen save

# → ~/Pictures/2024-08-19-screenshot-candidate.png

# Compare side-by-side using any image viewer

feh ~/Pictures/2024-08-19-screenshot.png ~/Pictures/2024-08-19-screenshot-candidate.png

Recording Videos for Animation Verification

For transitions, animations, or dynamic state changes, use the screen recording commands:

# Start full-screen recording

omarchy screenrecord --fullscreen

# Exercise the changed UI (open panels, toggle themes, trigger animations)

# Stop recording

omarchy screenrecord --stop-recording

# → ~/Videos/2024-08-19-recording.mp4

# Review the animation flow

mpv ~/Videos/2024-08-19-recording.mp4

Simulating User Input with wtype

When verifying interactive components like dialogs or menus that require user actions, use wtype to send synthetic keystrokes to background UIs. This is essential for testing state changes that automated captures might miss:

# Launch the UI process in background

my-omarchy-ui &
sleep 1

# Send navigation and selection keystrokes

wtype -k Right -k Return

# Verify the resulting state with a fresh screenshot

omarchy capture screenshot fullscreen save

Key Implementation Files

The visual verification workflow is backed by the following source files:

• agents/skills/visual-verification.md — Authoritative skill guide defining the three-step protocol, media capture standards, and wtype integration
• bin/omarchy-capture-screenshot — Implementation of the omarchy capture screenshot sub-commands
• bin/omarchy-capture-screenrecording — Implementation of the omarchy screenrecord sub-commands
• manual/12-screenshots-recording.md — User-facing documentation explaining screenshot and recording options
• manual/14-omarchy-cli.md — Command reference for the omarchy capture group

Summary

• Visual verification is mandatory for any change affecting Omarchy's styling, layout, panels, or animations
• Developers must capture reference media, apply changes, then capture and compare candidate media to spot regressions
• The omarchy capture suite provides screenshot fullscreen save and screenrecord commands for documentation
• Synthetic input via wtype validates interactive UI components without manual GUI interaction
• All procedures are authoritatively defined in agents/skills/visual-verification.md

Frequently Asked Questions

Why does Omarchy require manual visual verification instead of relying solely on automated tests?

Automated tests can verify functional logic but often miss subtle visual regressions like pixel-level clipping, spacing inconsistencies, animation timing errors, or focus ring artifacts. The Omarchy workflow treats the visual output as a first-class artifact that must be inspected in situ by a human to ensure the shell's quality remains high.

What file formats and locations does the omarchy capture suite use?

Screenshots are saved as PNG files to the user's Pictures folder, while screen recordings are saved as MP4 files to the Videos folder. Both use ISO-formatted timestamps in their filenames (e.g., 2024-08-19-screenshot.png) to ensure chronological sorting and easy reference-to-candidate matching.

How do I verify UI changes that require hidden or background interactions?

Use the wtype utility to send synthetic keystrokes to the UI process. For example, wtype -k Right -k Return navigates and selects options in selection dialogs or menus. After sending the input, capture a new screenshot with omarchy capture screenshot fullscreen save to verify the resulting visual state.

Where is the canonical visual verification protocol documented?

The authoritative reference is located at agents/skills/visual-verification.md in the repository root. This file defines the mandatory three-step process, approved capture methods, and integration patterns for the omarchy capture and wtype tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}