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. N adds a shade over the night side of the map, in four strengths. 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.
• Fourteen themes (midnight, nord, dracula, light, gruvbox, gruvbox-light, mono, green, amber, grey, paper, vaporwave, synthwave, colorblind), 12 or 24 hour clock, mouse support, and about 12,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.

The simplest way is pipx, which installs the terrahour command for your user:

pipx install terrahour
terrahour

If you do not have pipx, get it with sudo apt install pipx on Debian and Ubuntu or brew install pipx on macOS. If your shell cannot find terrahour afterwards, run pipx ensurepath once and open a new terminal.

To try it without installing anything: pipx run terrahour or uvx terrahour.

With pip, in a virtual environment. Recent Debian and Ubuntu refuse a plain pip install outside one. The command is then available whenever that environment is active:

python3 -m venv .venv && . .venv/bin/activate
pip install terrahour
terrahour

From a clone. There is nothing to build, so you can run it in place:

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

Updating

pipx upgrade terrahour

If you installed with pip, run pip install --upgrade terrahour in the same environment. In a clone, git pull. terrahour --version tells you which version you have.

Usage

Run terrahour. The first time it starts with a default set of cities: press a to add your own, d to remove one, * to mark the selected city as home, ? for every key and q to quit.

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 --night-shade 0.5                # shade the night side of the map (0 to 1)
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.

Window size

What you see depends on the size of your terminal window:

On a small map only the selected city is named, so the dots stay readable. Press c if you want to force the compact layout, or to go back.

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

python3 -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.