← NUILab Software

nuiClock / Get started / Overview

Get started

Overview

What nuiClock does, how to install it, how to use it, and its settings.

nuiClock 0.1.4

An extra clock for the macOS menu bar, set to the time zone you choose.

macOS shows one clock in the menu bar. nuiClock puts another next to it, for the place you keep converting to in your head: Madrid 14:05.

Download the app at nuiclock.software.nuilab.org.

What it does

  • Shows the time in one other time zone, in the menu bar.
  • Labels it with the city, your own text, or nothing.
  • Shows the time zone after the label, if you turn that on: as its abbreviation (MST, CET) or as its offset from GMT (GMT-7). For example FoCo MST 8:43 AM, or MST 8:43 AM with no label. A zone with no abbreviation in real use shows its offset.
  • Uses 12-hour time, 24-hour time, or whatever this Mac uses, with or without seconds.
  • Shows when the date there is not your date, as the day of the week (Tokyo Sun 08:15) or as a day count (Tokyo 08:15 +1d, Honolulu 21:15 -1d). You can also show the day of the week always, or nothing.
  • Opens a menu with the full date in that zone, the zone’s name and UTC offset, and how far it is from your local time.
  • Finds a place by city, country, zone name, abbreviation (EST, CET) or offset (utc+9). Besides the city of each time zone it knows about 34,000 more cities, so you can choose Fort Collins and not only Denver. The clock then shows the city you chose.
  • Keeps a second clock, if you turn it on, in the menu that opens when you click the first: its time, date, zone and difference from local time. It gets its own place in the menu bar only if you choose that.
  • Swaps the two clocks in one click: the second becomes the first, and the first becomes the second.
  • Opens at login, if you turn that on.

The app has no Dock icon and no main window. It does not use the network and it collects nothing.

Requirements

macOS 13 (Ventura) or later to run, on Apple silicon or Intel. To build the app you need Xcode 16 or later, or Apple’s Command Line Tools with Swift 6 (xcode-select --install). The unit tests need Xcode.

It was developed and tested on macOS 27, built with Xcode 16.2 and with the Command Line Tools (Swift 6.4).

Install

Download the app from nuiclock.software.nuilab.org/download, unpack it, and move nuiClock to your Applications folder. macOS asks you to confirm the first time you open it, because the app is not notarized by Apple. That page says how.

Or build it on your own Mac. An app built there opens without that question:

git clone https://git.nuilab.org/f.ortega/nuiClock.git
cd nuiClock
make install

make install builds the app, copies nuiClock.app to /Applications, and opens it. To install for one user, run make install DEST=~/Applications.

Use

The first time it opens, nuiClock shows its Settings window. Search for a city or a time zone and click it. The menu bar changes as you choose.

After that, click the clock in the menu bar for the date, the zone and the difference from local time, and for Settings… and Quit nuiClock. Opening nuiClock again from Finder or Spotlight also shows Settings.

Settings has a tab for each clock. The second clock is off until you turn it on in its tab. It then shows in the first clock’s menu, and clicking it there opens its settings. Turn on Also show it in the menu bar to give it a place of its own.

Swap clocks, next to the tabs, makes the second clock the first and the first the second. You can choose the second clock’s place and text while it is off, so it can hold a place you swap to now and then without showing it. While the second clock is on, its part of the menu has Swap Clocks too.

The time zones, their rules and their abbreviations are the tz database that ships with macOS, so they follow the system’s time zone updates. Where the database gives a zone only an offset, macOS’s own table of common abbreviations fills in (GST for Dubai). The cities are built into the app.

Settings from Terminal

Settings live in the org.nuilab.nuiClock defaults domain. Quit nuiClock, change a value, and open it again:

defaults write org.nuilab.nuiClock timeZoneIdentifier Asia/Tokyo
KeyValuesDefault
timeZoneIdentifiera tz database name, such as Europe/MadridUTC
cityNamethe city to show for that zone, such as Fort Collins; empty shows the zone’s own cityempty
labelStylecity, custom, hiddencity
customLabeltext, used when labelStyle is customempty
zoneStylehidden, abbreviation, offsethidden
hourStylesystem, twelveHour, twentyFourHoursystem
showSeconds-bool true or -bool falsefalse
weekdayStylenever, whenDifferent, always, dayOffsetwhenDifferent

The second clock has the same keys with second. in front, such as second.timeZoneIdentifier, and two more:

KeyValuesDefault
second.enabled-bool true or -bool falsefalse
second.showInMenuBar-bool true or -bool falsefalse

Uninstall

Turn off Open at login in Settings, quit nuiClock, and move it from Applications to the Trash. In a clone of the repository, make uninstall quits it and removes it from /Applications for you. Then remove its settings:

defaults delete org.nuilab.nuiClock

Development

swift test          # unit tests
make app            # build/nuiClock.app for this Mac
make universal      # the same, for Apple silicon and Intel together
make dist           # that app zipped for download: build/nuiClock-<version>-macos.zip
make run            # build and open it
make icon           # draw Resources/AppIcon.icns again
make cities         # fetch the GeoNames city list and write Resources/cities.tsv again

The code is a Swift package with two parts. Sources/NuiClockCore holds the time zone logic and has no user interface, so the tests cover it. Sources/nuiClock is the app: AppKit for the menu bar item, SwiftUI for the Settings window.

make app signs the app ad hoc, which is enough for the Mac that built it. To sign with a Developer ID, set CODESIGN_IDENTITY.

To watch the text of both clocks as it changes, and how many cities the Settings search loaded:

log stream --level debug --predicate 'subsystem == "org.nuilab.nuiClock"'

Credits

The city list comes from GeoNames (opens in new tab) and is licensed under CC BY 4.0 (opens in new tab). It is the GeoNames cities15000 list (places with more than 15,000 people, and capitals), reduced to name, region, country and time zone by scripts/make-cities.sh.

License

Copyright (C) 2026 Francisco R. Ortega

nuiClock is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

nuiClock is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License in LICENSE (opens in new tab) for more details.

Source: README.md in the nuiClock repository, the same file that ships with the code.