wxterm

A terminal-based weather application built in Go. View current conditions, hourly and daily forecasts, and animated precipitation radar — all from your terminal.

Personal Note: This project began as one of my first from-scratch builds using Claude and has been a personal idea I’ve wanted to explore for quite some time. The map renderer milestone is now complete: the radar base map is rendered from vector tiles using a Go port of the approach in mapscii, replacing the original raster-tile renderer.

• Current Weather — Temperature, "feels like", humidity, wind, pressure, cloud cover, precipitation, visibility, and sunrise/sunset times with ASCII-art weather icons
• Hourly Forecast — 24-hour forecast table with temperature, humidity, wind speed, and precipitation
• Daily Forecast — 7-day outlook with high/low temps, precipitation probability, and wind speeds
• Animated Radar — Live precipitation radar covering the past 2 hours at 10-minute intervals (plus short-term nowcast frames when available), over a vector-tile base map rendered with Unicode Braille characters — real text labels for cities and water, national/state borders at every zoom (plus county lines at zoom 9+), with pan, zoom, and animation playback controls
• Location Search — Search by city name or enter coordinates manually; save favorite locations for quick access
• Auto-Detection — Automatically detects your location via IP geolocation on startup
• Unit Toggle — Switch between metric (°C) and imperial (°F) units on the fly
• Cross-Platform — Works on Windows, macOS, and Linux
• No API Keys Required — Uses free, open APIs (Open-Meteo, RainViewer, OpenFreeMap)
• Mouse Support — Full mouse cell motion support via the Bubble Tea framework

Screenshots

Current Conditions	Hourly Forecast
Daily Forecast	Local Radar
Regional Radar	Storm Detail

• Go 1.26 or later
• A terminal emulator with Unicode and 256-color support (most modern terminals work)

git clone https://github.com/psteger/wxterm.git
cd wxterm
go mod download

Windows:

go build -o wxterm.exe .

macOS / Linux:

go build -o wxterm .

go run .

Launch wxterm by running the built binary:

./wxterm        # macOS / Linux
wxterm.exe      # Windows

The app starts in full-screen mode and auto-detects your location. No command-line arguments are needed.

wxterm stores its configuration at:

Windows:

%AppData%\wxterm\wxterm.json

macOS / Linux:

~/.config/wxterm/wxterm.json

{
  "default_location": {
    "name": "New York",
    "latitude": 40.7128,
    "longitude": -74.006,
    "country": "United States",
    "admin1": "New York"
  },
  "saved_locations": [
    {
      "name": "San Francisco",
      "latitude": 37.7749,
      "longitude": -122.4194,
      "country": "United States",
      "admin1": "California"
    }
  ],
  "use_fahrenheit": false
}

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a branch for your feature or fix: git checkout -b my-feature
3. Make your changes and add tests where appropriate
4. Run tests to make sure everything passes:

   go test ./...

5. Commit with a clear message describing what you changed
6. Open a pull request against main

If you find a bug or have a feature request, please open an issue with:

• A clear description of the problem or suggestion
• Steps to reproduce (for bugs)
• Your OS and terminal emulator

This project is licensed under the MIT License. See the LICENSE file for details.

• Bubble Tea — Terminal UI framework
• Lip Gloss — Terminal styling
• Bubbles — UI components (spinner, text input)
• Open-Meteo — Free weather forecast and geocoding API
• RainViewer — Precipitation radar tile data
• OpenFreeMap — Vector base map tiles (OpenStreetMap data)
• mapscii — Terminal map rendering approach and style, ported to Go for the radar base map
• ip-api.com — IP-based geolocation