terrahour

A world clock for the terminal, with a map that shows where it is daytime and a 24-hour timeline that shows when your cities are at work.

Main view: the day and night map above a timeline per city

A quick tour: scrubbing time, exchanges, DST radar, ambient view

What it does

• Map with day and night. The world is drawn in braille dots, shaded by sunlight, and coloured by time zone. Every city you track gets a marker. Zoom with + - or the mouse wheel, drag to pan.
• A timeline per city. Each row is a 24-hour bar with the working hours lit up. The overlap row at the bottom shows the window when everybody is at their desk.
• Scrub through time. Arrow keys move in 15-minute steps, g jumps to any time ("15:30", "3pm", "+2h", "2026-10-05 09:00"), r snaps back to live.
• DST radar. D lists the next clock change for every city and, more usefully, whether the gap between you and them is about to shift by an hour.
• Stock exchanges. M swaps the city list for the ten biggest exchanges with their real trading sessions, lunch breaks included.
• Alerts. A sets a daily reminder in another city's time, a ping when an office or exchange opens or closes, or a plain timer. They ring the bell and send a desktop notification while the app is open.
• Weather, if you want it. W shows the current temperature next to each city (Open-Meteo, needs network, off by default).
• Ambient view. V turns the whole terminal into a big clock over the map that cycles through your cities. Nice on a spare monitor.
• Fits anywhere. Below about 76 columns it switches to a compact layout that works in a tmux split. --line prints a one-liner for a status bar.
• Six themes (midnight, nord, dracula, light, mono, colorblind), 12 or 24 hour clock, mouse support, and about 6,000 cities built in with online lookup for the rest.

Exchanges	Compact layout for a tmux split

DST radar	Adding a city

Ambient view	Light theme

Install

You need Python 3.9 or newer, a terminal with truecolor support (almost all of them these days) and a UTF-8 locale. Developed on Linux. macOS is covered by the automated tests, but I have not tried it by hand. On Windows use WSL, the app relies on a Unix terminal.

pipx install git+https://github.com/ACoci86/terrahour

Then run terrahour. If your shell cannot find the command, run pipx ensurepath once and open a new terminal.

or, without pipx, in a virtual environment (recent Debian and Ubuntu refuse a plain pip install outside one):

python3 -m venv .venv && . .venv/bin/activate
pip install git+https://github.com/ACoci86/terrahour
terrahour

The command is available whenever that environment is active.

or just clone it and run it in place, there is nothing to build:

git clone https://github.com/ACoci86/terrahour
cd terrahour
python -m terrahour

Usage

terrahour                                  # your saved cities (a sensible default set the first time)
terrahour Europe/Berlin "Home=America/Chicago" Naples   # a one-off set of zones or city names, not saved
terrahour --markets                        # start in the exchange view
terrahour --at 2026-10-05T09:00Z           # start frozen at a given time
terrahour --theme nord --12h
terrahour --ambient                        # straight into the screensaver view
terrahour --reset                          # forget saved cities and settings

Press ? inside the app for the full list of keys. The ones you will use most:

Everything you change in the app (cities, theme, home, working hours, alerts) is saved to ~/.config/terrahour/config.json. Zones given on the command line are session-only and leave that file alone.

Status bars and scripts

$ terrahour --line
SF 07:30 · NY 10:30 · LON 14:30 · UTC 14:30 · DUB 18:30 · MUM 20:00 · SIN 22:30 · TOK 23:30 · SYD 01:30+1

$ terrahour --watch            # the same line, updating in place (good in a small tmux pane)
$ terrahour --tmux             # with tmux colour codes, for your status-right
$ terrahour --json --at 2026-03-18T14:30Z | jq '.cities[] | select(.open)'

The JSON includes local time, UTC offset, whether the city is inside working hours, minutes until that changes, and the next clock change. --once --size 120x40 prints a single frame of the full UI, which is how the screenshots above were made.

Network

Two features talk to the internet, and both are optional:

• While you type in the "add city" box, names that are not in the built-in list are looked up through the Open-Meteo geocoding API.
• Weather, when you turn it on with W, comes from the Open-Meteo forecast API.

Set TERRAHOUR_OFFLINE=1 to switch both off. Nothing else leaves your machine.

How it is put together

It is a single Python package with no third-party dependencies. The pieces:

The map is a 0.25 degree land mask folded into a summed-area table, so any zoom level can ask "how much of this box is land?" in constant time, and the braille cells come straight out of that. Sun position uses the usual NOAA approximation, good to a few minutes.

Development

python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest

The tests do not need a terminal or the network: they compose frames in memory and drive the app through the same key handler the terminal loop uses. tools/screenshots.py regenerates everything in docs/ (it needs Pillow and the DejaVu fonts).

Data and credits

• City list derived from GeoNames (CC BY 4.0).
• Land mask rasterised from Natural Earth (public domain).
• Geocoding and weather from Open-Meteo (CC BY 4.0).
• Time zone rules come from your operating system's tz database through Python's zoneinfo.

License

MIT. See LICENSE.