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

> Learn how Omarchy's visual verification ensures UI changes are flawless. Capture and compare screenshots or videos to catch regressions before committing code.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-19

---

**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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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:

```bash

# 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:

```bash

# 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:

```bash

# 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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/manual/12-screenshots-recording.md) — User-facing documentation explaining screenshot and recording options
- [`manual/14-omarchy-cli.md`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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`](https://github.com/basecamp/omarchy/blob/main/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.