Weather, drawn in text.
wxterm is a full-screen terminal weather display: a live radar loop over a line-drawn map, conditions, a 48-hour graph, tides, the moon and the forecast, in ASCII, box-drawing and braille. It runs on an old laptop as a kiosk with no desktop, or in any big terminal window.
What's on the screen
- Radar
- The last two hours of radar, looping over coastlines, borders, highways and towns, with 25 and 50 mile rings.
- Now
- Temperature in seven-segment digits, feels-like, wind, humidity, pressure trend, and any alerts.
- 48 hours
- Temperature and dew point as braille line plots over rain-chance bars.
- Tide · moon
- The tide curve through tomorrow with every high and low, plus the moon phase, rise and set.
- 5-day
- Highs, lows, rain chance and a few words for each day.
- Rotating
- A panel that cycles between the forecaster's discussion, typed out like a teletype, the surf, and temperatures from the coast inland.
Small touches
- l
- Next location. Ten are built in: yours plus nine demo cities from San Francisco to Tokyo.
- g
- Record exactly one radar loop as a GIF. Every GIF on this page was made that way.
- f
- Big digits as segments, braille dots or blocks.
- s
- Shuffle the layout. It also happens every 15 minutes, so nothing burns in.
- Any size
- Built for 240×62 cells at 1080p. The layout follows the terminal down to about 160×45.
Install
On any Linux or macOS machine with Docker and Python 3.11 or newer:
$ git clone https://github.com/jdoscher/wxterm && cd wxterm
$ python3 scripts/new-location.py home 47.6062 -122.3321 --title "SEATTLE"
$ python3 scripts/gen-compose.py
$ cp .env.example .env # your contact for the NWS API
$ docker compose up -d --build
$ cd display && python3 -m venv .venv && .venv/bin/pip install -e .
$ .venv/bin/wxterm
new-location.py takes a name and coordinates and looks up the rest: timezone, weather
station (NWS in the US, the nearest airport elsewhere), tide and water-temperature stations,
surf spot, map lines and town labels. Your home location is gitignored.
Outside the US you get airport observations and the Open-Meteo forecast. Alerts and the forecast discussion are NWS products, so those panels are skipped.
A kiosk, not a window
wxterm was built for an old ThinkPad that does nothing else. One script turns a Debian or Ubuntu machine into a weather terminal: it boots straight to the display, with no login screen and no desktop, and ignores the lid and sleep.
$ cp kiosk/kiosk.conf.example kiosk/kiosk.conf
$ python3 scripts/new-location.py home LAT LON --title "YOUR TOWN"
$ sudo bash kiosk/setup.sh && sudo reboot
Under the hood it's cage running
foot fullscreen. The bare Linux console can't
show braille, so wxterm skips it. One config file covers every setting, and
mode.sh desktop gives you the normal desktop back.
The data side runs in Docker, one small collector per location, so switching cities is instant. The display itself is Python with Textual.
Ask your LLM
An optional, read-only MCP server lets Claude or any MCP client read the weather and the kiosk's status, and take a screenshot. It can't change anything. It's off by default, requires a token, and refuses requests from browsers.
$ claude mcp add --transport http wxterm \
http://KIOSK:8090/mcp --header "Authorization: Bearer TOKEN"
Is it raining in San Francisco?
get_radar_summary(location="sf")
Yes: heavy rain over the city right now, drifting west-southwest at about 12 mph.
Is the kiosk running hot?
get_status
No. The CPU is at 42 °C, both batteries are full on AC power, and all ten collectors are up to date.
Free data, no keys
| What | Source |
|---|---|
| Conditions | NWS stations in the US, aviationweather.gov METARs elsewhere |
| Forecast | NWS, and Open-Meteo for hourly data and places outside the US |
| Radar | RainViewer composite, with IEM NEXRAD as a US fallback |
| Tides | NOAA CO-OPS, or Open-Meteo's sea-level model where there's no gauge |
| Surf | Open-Meteo marine |
| Sun · moon | Computed locally |
| Maps | Natural Earth (public domain) and GeoNames town names |
Around the world



