URL Routing and Webapps

Route matching URLs to Omarchy webapps while keeping the normal browser fallback.

The custom URL handler makes http and https links choose between two launch paths:

Matching URLs open as standalone Omarchy webapps.
Everything else opens in Chromium as a normal browser tab or window.

This keeps common app-like sites in dedicated windows without making every link a webapp.

Files

The handler is part of the stowed Hypr package:

Path	Purpose
`~/.config/hypr/bin/timmo-url-handler`	Runtime URL router.
`~/.config/hypr/bin/timmo-setup-url-handler`	Idempotent install/remove helper.
`~/.config/hypr/url-handler/patterns.conf`	Routing rules.
`~/.config/hypr/url-handler/omarchy-url-handler.desktop`	Desktop entry used by xdg mime handling.

Edit the source files in the dotfiles repo, then run dot stow:

~/.config/dotfiles/hypr/.config/hypr/

Install the handler

Run the setup helper after the Hypr package is stowed and ~/.config/hypr/bin is on PATH:

timmo-setup-url-handler

The setup helper:

Creates or updates the desktop file.
Symlinks it into ~/.local/share/applications/.
Sets it as the default handler for http, https, about, and unknown schemes in ~/.config/mimeapps.list.
Backs up mimeapps.list before changing it.
Runs update-desktop-database when that command is available.

Pattern rules

Rules live in:

~/.config/hypr/url-handler/patterns.conf

Each non-comment line starts with an action and a glob pattern:

webapp:discord.com
webapp:*.youtube.com
browser:*.gitlab.com

Patterns are checked against both the full URL and the extracted domain. The first matching rule wins.

If nothing matches, the default action is browser.

Add a webapp route

Edit ~/.config/dotfiles/hypr/.config/hypr/url-handler/patterns.conf.
Add a webapp:<pattern> line above any broader browser rule.
Run dot stow.
Test with timmo-url-handler <url>.

Example:

webapp:calendar.google.com
webapp:*.calendar.google.com

Force a normal browser route

Use browser:<pattern> when a site should not become a webapp:

browser:gitlab.com
browser:*.gitlab.com

Browser routes launch Chromium directly through uwsm-app so the default handler does not recurse back into itself.

Test routing

Run the handler directly:

timmo-url-handler https://github.com
timmo-url-handler https://gitlab.com

To check the desktop default:

xdg-mime query default x-scheme-handler/https

Expected output:

omarchy-url-handler.desktop

Remove the handler

timmo-setup-url-handler remove

The remove path deletes the applications symlink and desktop file. If the setup backup exists, it restores ~/.config/mimeapps.list from that backup. If no backup exists, clean up mimeapps.list manually.

Troubleshooting

If the setup script cannot find timmo-url-handler, check that the Hypr bin directory is on PATH and run dot stow again.

If a URL opens in the browser when it should be a webapp, put the more specific webapp: rule before broader browser: rules and test the exact URL with timmo-url-handler.

If every browser launch loops, check that the browser branch still launches /usr/bin/chromium directly rather than calling xdg-open.