Omarchy World Clock

Omarchy World Clock adds a small world-clock entry point next to Omarchy's center clock and opens a multi-timezone popup for planning across places. It supports the Omarchy 4 shell and the legacy Omarchy 3 Waybar.

Screenshots

Ristretto - Industrial Moon - Waybar At a Glance

Rose Pine - Read View

Matte Black - Add Location

Kanagawa - Edit Mode

What It Does

• Adds a compact world icon next to Omarchy's center clock.
• Toggles the popup on left click and opens Omarchy's timezone selector on right click.
• Opens beneath the top bar and follows Omarchy 4's active popup colors, border, opacity, and corner radius.
• Opens a popup with live clocks for a user-managed timezone list.
• Supports manual reference-time conversion across the visible clock cards.
• Lets you add and remove timezones.
• Searches local timezone data first, then can use Open-Meteo geocoding for unresolved city/place searches.
• Follows the system time format.
• Adapts popup colors to the active Omarchy theme palette.
• Stores state in ~/.config/omarchy-world-clock/config.json.

Install

AUR

Recommended on Arch/Omarchy via AUR, no Rust toolchain required:

yay -S omarchy-world-clock-bin

If you use another AUR helper, install the same package name with that helper. Then add the module to the current user's bar:

omarchy-world-clock install

The AUR package installs only the system binary. install detects Omarchy 4's shell or Omarchy 3's Waybar, patches the matching user config, reloads the bar, and creates the world-clock config file.

To patch non-default paths:

omarchy-world-clock install-shell \
  --shell-config "$HOME/.config/omarchy/shell.json" \
  --command-path "$(command -v omarchy-world-clock)" \
  --user-config "$HOME/.config/omarchy-world-clock/config.json"

Omarchy 4 Shell

On Omarchy 4, the installer adds a command widget immediately after omarchy.clock in ~/.config/omarchy/shell.json. The existing weather, system-update, and indicator widgets remain in place. The shell hot-reloads the config.

The popup reads the active palette and [popups] surface roles from ~/.local/state/omarchy/current/theme, with the Omarchy 3 theme location kept as a fallback.

Manual entry:

{
  "id": "world-clock",
  "type": "command",
  "exec": "/usr/bin/omarchy-world-clock module",
  "interval": 2,
  "onClick": "/usr/bin/omarchy-world-clock toggle",
  "onRightClick": "omarchy-menu-timezone"
}

Place it after { "id": "omarchy.clock" } in bar.layout.center.

Omarchy 3 Waybar

If you prefer to edit Waybar yourself, add the module to modules-center in ~/.config/waybar/config.jsonc:

"modules-center": ["clock", "custom/world-clock"]

Then add this top-level module block. If you did not install from AUR, replace /usr/bin/omarchy-world-clock with your installed binary path. Keep normal JSON comma placement for where you insert the block.

"custom/world-clock": {
  "exec": "/usr/bin/omarchy-world-clock module",
  "return-type": "json",
  "interval": 2,
  "format": "{}",
  "tooltip": true,
  "on-click": "/usr/bin/omarchy-world-clock toggle",
  "on-click-right": "omarchy-launch-floating-terminal-with-presentation omarchy-tz-select"
}

Add the matching styles to ~/.config/waybar/style.css:

#custom-world-clock {
  min-width: 12px;
  margin-left: 6px;
  margin-right: 0;
  font-size: 12px;
  opacity: 0.72;
}

#custom-world-clock.active {
  opacity: 1;
}

Restart Waybar after editing:

omarchy-world-clock restart-waybar

Script Install

Alternative install, no Rust toolchain required:

curl -fsSL https://raw.githubusercontent.com/olivoil/omarchy-world-clock/master/install.sh | bash

From a local checkout:

./install.sh

This:

• downloads the latest prebuilt release binary
• installs missing Arch/Omarchy runtime packages (gtk4, gtk4-layer-shell)
• installs it under ~/.local/share/omarchy-world-clock
• writes ~/.local/bin/omarchy-world-clock
• patches and reloads ~/.config/omarchy/shell.json on Omarchy 4
• otherwise patches and restarts the Omarchy 3 Waybar config and style

Install a specific release:

OMARCHY_WORLD_CLOCK_VERSION=v0.1.0 ./install.sh

Build from source instead:

./install.sh --build-from-source

Uninstall

./uninstall.sh

To also remove saved user state:

./uninstall.sh --purge

Build And Run

Source builds require Rust/Cargo plus GTK4 development packages.

Build:

cargo build

Run the bar module payload directly:

cargo run -- module

Open the popup:

cargo run -- popup

Toggle the popup:

cargo run -- toggle

Run tests:

cargo test

Run the local PR checks:

scripts/ci.sh

This mirrors the checks this project would normally put in a GitHub Action: formatting, Clippy, Rust tests, and the shell installer tests.

Sign off the current commit after the local checks pass:

scripts/signoff.sh

This requires GitHub CLI auth and Basecamp's signoff extension:

gh auth login
gh extension install basecamp/gh-signoff

To make signoff a required merge check on GitHub, run gh signoff install from the default branch.

If branch protection requires partial signoffs, pass the names through:

scripts/signoff.sh tests lint security

Runtime Notes

This repo assumes an Omarchy-like environment with:

• Hyprland
• Omarchy shell/Quickshell on Omarchy 4, or Waybar on Omarchy 3
• GTK4
• gtk4-layer-shell

Release installs do not require Rust or Cargo on the user's machine. On Arch/Omarchy, install.sh checks for the GTK runtime packages and installs missing packages with sudo pacman unless OMARCHY_WORLD_CLOCK_SKIP_RUNTIME_DEPS=1 is set. To install them manually:

sudo pacman -S --needed gtk4 gtk4-layer-shell

The supported CLI surface is:

• omarchy-world-clock module
• omarchy-world-clock toggle
• omarchy-world-clock popup
• omarchy-world-clock install
• omarchy-world-clock uninstall
• omarchy-world-clock reload
• omarchy-world-clock install-shell
• omarchy-world-clock uninstall-shell
• omarchy-world-clock install-waybar
• omarchy-world-clock uninstall-waybar
• omarchy-world-clock restart-waybar

Configuration

State lives in:

~/.config/omarchy-world-clock/config.json

Example:

{
  "version": 4,
  "timezones": [
    {
      "timezone": "America/Cancun",
      "label": "Home",
      "latitude": 21.1619,
      "longitude": -86.8515
    },
    {
      "timezone": "Europe/Paris",
      "label": "Rennes",
      "latitude": 48.1173,
      "longitude": -1.6778
    }
  ]
}

Optional privacy setting:

{
  "disable_open_meteo_geolocation": true
}

When this is true, search uses only local timezone names, aliases, and bundled timezone data. Existing coordinates already saved in the config still work.

Third-Party Services

Omarchy World Clock calls Open-Meteo's Geocoding API only for unresolved city/place searches, and only when disable_open_meteo_geolocation is not set to true. The app does not use a project API key; requests are made directly from the user's machine.

Open-Meteo's free API is for non-commercial use with published rate limits, and its API data is licensed under CC BY 4.0. Remote search results are attributed inline in the popup with a link to Open-Meteo, as required by their licence.

Privacy note: the typed search text is sent to Open-Meteo for these remote lookups. Open-Meteo's terms say free API logs may include IP addresses and request details for technical reasons and troubleshooting, with log deletion after 90 days. See Open-Meteo's Terms & Privacy and Licence.

Docs

• Product behavior spec: docs/specs.md
• Maintainer release process: docs/release.md

Disclaimer

Omarchy World Clock is an unofficial project and is not affiliated with Basecamp or the Omarchy project.