OmaRest

Healthy limits for your digital focus

OmaRest turns long, continuous app sessions into deliberate breaks. Choose an application, set a comfortable allowance, and let a calm break screen mark the stopping point across every display.

Built for Omarchy 4 · Current build: v1.0.1

Install · See how it works · View controls

The ten-second preview uses the same multi-monitor break surface as a real boundary without changing normal tracking or activity totals.

Why OmaRest?

Desktop tools are good at helping us start. They are less good at making the stopping point visible. OmaRest adds a clear, application-aware boundary without inspecting what you read, type, or browse.

The problem	OmaRest's response
A focused session quietly turns into an hour	Give each application its own allowance and break rhythm
A quick app switch resets an ordinary timer	Reset only after the configured time away
A break on one display is easy to ignore	Cover every connected display with one synchronized break
Screen-time tracking can feel invasive	Observe the active app class only and keep all data local

What you can do

• Set a boundary for any installed app. Browse the same application catalog used by Omarchy or start with the app currently in front.
• Choose a rhythm that fits the work. Start with 20/10, 30/5, or 45/5 focus-and-break presets, then tune either value directly.
• Make brief switches count honestly. A session resets only after its configured away duration, so checking another window does not erase the elapsed time.
• Limit boundaries by schedule. Choose active days and a daily time window, including overnight schedules.
• Get a warning before the break. Start the break from the notification or continue until the allowance ends.
• Pause when context changes. Pause tracking for 15 minutes, one hour, or until you explicitly resume it. Middle-clicking the bar widget toggles a 15-minute pause.
• Leave safely when necessary. Hold Space or press and hold the break control to end early. Ctrl+Shift+Esc is always available as an immediate emergency dismissal.
• Keep the experience comfortable. Reduce break-screen motion and choose the hold duration used for an intentional early exit.

A calmer stopping point

When an allowance runs out, OmaRest opens one synchronized surface per monitor. The countdown stays visually quiet, the prompt suggests a small physical reset, and the configured application can wait until the timer finishes.

The break remains dismissible. Completing it or ending it early resets that application's continuous session, while OmaRest records the two outcomes separately in the local daily summary.

Install

OmaRest is tested with Omarchy 4.0 and the current Quickshell-based Omarchy Shell. Its runtime is the standard Omarchy desktop stack: omarchy, omarchy-shell, Quickshell, Hyprland, and hyprctl. It requires no additional package, account, API, browser extension, or network service.

1. Add the plugin

omarchy plugin add https://github.com/mirashif/omarest.git --enable --yes

OmaRest places its widget in the right bar section by default.

2. Set your first boundary

Click the OmaRest bar icon, choose an installed application, then select a starter rhythm or enter your own focus and break times. Warning timing, the away-reset duration, active days, and schedule live under Advanced options.

The popup can also be opened directly:

omarchy-shell shell summon com.mirashif.omarest '{}'

3. Preview the break

Open Settings → Break preview → Preview. OmaRest shows the real break surface for ten seconds on every monitor without changing normal usage or activity totals.

How it works

1. OmaRest observes the active Wayland application class.
2. A matching boundary accumulates time only while that app stays in front and the session is neither idle nor locked.
3. Switching away preserves the session until the configured away-reset time is reached.
4. OmaRest warns at the selected threshold, then opens the synchronized break when the allowance is exhausted.
5. Finishing or intentionally ending the break resets that application's continuous session.

Delayed ticks are capped, so suspend, a stalled shell, or a clock jump cannot inflate foreground usage. A five-second hyprctl -j activewindow check backs up the primary Wayland toplevel signal.

Controls and shortcuts

Control	What it does
Click the bar widget	Open or close OmaRest
Middle-click the bar widget	Pause for 15 minutes, or resume when already paused
Ctrl+N	Add a focus boundary
Ctrl+,	Open Settings
Ctrl+Enter	Save the boundary being edited
Escape	Go back one level or close the popup
Hold Space	End a break early after the configured hold duration
Ctrl+Shift+Esc	Dismiss the break immediately in an emergency

Personal, local, and private

OmaRest stores focus-boundary configuration, per-boundary elapsed time, and 31 days of aggregate outcomes in two atomic JSON files:

${XDG_CONFIG_HOME:-~/.config}/omarest/config.json
${XDG_STATE_HOME:-~/.local/state}/omarest/state.json

It never persists window titles, URLs, browser history, screenshots, typed content, or complete browsing activity. It does not use the network.

This release is application-aware, not website-aware. Domain-specific browser rules would require a separately permissioned browser companion and are not part of OmaRest.

Update

omarchy plugin update com.mirashif.omarest --yes

If the running widget does not refresh after an update, restart Omarchy Shell:

omarchy restart shell

Remove

Use Settings → Local data → Delete data first if you also want to erase boundaries and activity totals. Then disable and remove the plugin:

omarchy plugin disable com.mirashif.omarest
omarchy plugin remove com.mirashif.omarest

Removing the plugin does not silently delete the two local JSON files. Delete the omarest XDG directories separately only when you want a complete reset.

Troubleshooting

Check the live service state:

omarchy-shell com.mirashif.omarest status | jq

The status reports initialization, the active app class, current phase, pause state, rule count, input source, and storage or source errors. To exercise the break surface independently of a boundary, run:

omarchy-shell com.mirashif.omarest test

For a stale popup or an unexplained shell error, restart the shell and inspect its recent log:

omarchy restart shell
qs log -p "$OMARCHY_PATH/shell" -t 100 | rg -i 'omarest|warning|error'

Development

Install the pinned Node development dependency with npm ci, then run:

npm run check
npm run qml:check
npm run omarchy:validate

The suite covers matching, schedules, continuous sessions, warnings, breaks, early endings, pauses, suspend-sized time jumps, daily rollover, retention, theme contracts, and IPC signatures. The staged Omarchy validation excludes development dependencies because plugin trees may not contain symlinks.

See CONTRIBUTING.md for change requirements, docs/architecture.md for internal contracts, and docs/manual-validation.md for the compositor smoke test.

Scope and provenance

OmaRest is an original clean-room implementation. It is not a port or fork of Cat Gatekeeper and does not use that project's code, copy, branding, or assets. The research boundary is recorded in RESEARCH.md.

OmaRest is released under the MIT License.