SIGHTING CONFIRMED

ISSQUATCH

A floating ISS tracker for Omarchy. It shows where the station is and who's aboard, and sends a notification ten minutes before a pass you can see from home.

INSTALL

For Omarchy with the Lua Hyprland config. It needs Python 3.11 or later, which Omarchy already has.

$ curl -fsSL https://raw.githubusercontent.com/squatchware/issquatch/main/install.sh | bash

Then press Super Alt I to open it and l to set your location. The installer is short and worth reading first: install.sh. It backs up anything it edits, and rolls itself back if Hyprland reports a config error.

A HEADS-UP BEFORE EACH PASS

You can only see the station when the sun is lighting it and your sky is dark. That happens on a few evenings or mornings a week, for a few minutes at a time. issquatch works out when, and ten minutes before each pass it sends a desktop notification like this one:

ISS overhead in 10 minLook NW at 20:35. It climbs to 53° and heads ESE, visible for 5m 50s.

A systemd timer does the checking every five minutes, so the map doesn't need to be open. Passes that stay below 20° are skipped, because trees and rooftops usually hide them. You can change the warning time and the cut-off in ~/.config/issquatch/config.toml, or install with ISSQUATCH_NOTIFY=0 to go without.

$ issquatch passes
ISS passes over London (local time)

  when              visible     max  path
  Sun 27 Sep 20:34  5m 20s      23°  W → SSE
  Tue 29 Sep 20:38  1m 50s      11°  WSW → SSW

THE PANEL

Next to the map are the live numbers: position, height, speed, the country or ocean below, and the minutes until the station's next sunrise or sunset. Under them are three pages.

Passesthe ones you can see from home, with the direction to look and how high each one climbs

Crewwho's aboard, with flag, agency and days in space, plus anyone on China's Tiangong station

Stationthe docked spacecraft and how long each has been there

The station page: five docked spacecraft (Crew-12 Dragon, Cygnus NG-24, two Progress freighters and Soyuz MS-29) with flags and days docked, then orbit number 58,763, one lap every 93 minutes, 15.5 sunrises a day and day 10,173 in orbit. — The station page

IT FOLLOWS YOUR THEME

The colours come from your Omarchy theme's colors.toml, and the map redraws when you switch themes. Here it is in four Retro Pack themes.

issquatch in four themes: Commodore 64 blues, Phosphor Green, Nixie oranges on smoky black, and Teletext's bright greens and yellows. — c64 · phosphor-green · nixie · teletext

THE MANUAL

Super Alt Iopen the map, or focus it if it's already open

Tab · 1 2 3next page · passes, crew, station

lset your location: a town, an address or lat, lon, then pick from the matches

t · r · qtoggle the ground track · refresh the orbit · quit

$ issquatch setup "Glasgow"   # or press l in the map
$ issquatch passes --week    # --all adds the unlit ones
$ issquatch crew             # who's aboard, with flags
$ issquatch now --json       # for scripts and bars
$ issquatch notify --test    # send the next alert now

WHAT IT TOUCHES

~/.config/hypr/issquatch.luathe floating window rule and keybinding

~/.config/hypr/hyprland.luaone line appended to load the file above

~/.config/systemd/user/issquatch-notify.*the pass-notification timer

~/.local/share/issquatch/a private Python virtualenv

~/.local/share/icons/hicolor/*/apps/issquatch.*the app icon

~/.local/share/applications/issquatch.desktopthe app menu entry

~/.local/bin/issquatchthe launcher

~/.config/issquatch/your location

install.sh --uninstall removes all of it except your location.

HOW IT WORKS

The station's orbital elements come from CelesTrak and are propagated with SGP4, the model they're made for. Positions match wheretheiss.at to a tenth of a degree, and pass times match the Skyfield astronomy library to the second. The coastlines are Natural Earth's, drawn with Unicode 16 octants: eight square pixels to a character, or two in terminals that can't draw octants. About 850 lines of Python, MIT licensed.

0.1°position error against wheretheiss.at

1 spass-time error against Skyfield

5 minbetween notification checks

6 hbetween crew-list updates

When you set your location, the place name is looked up once with OpenStreetMap's Nominatim. After that, the only downloads are the orbit from CelesTrak and the crew list from corquaid's ISS APIs. The country below the station is worked out offline from Natural Earth's borders. Not affiliated with NASA or any space agency.

GET IT

Free and MIT licensed. Bug reports and pull requests are welcome on GitHub.