A collection of simple, asynchronous, and configurable prompt sections for the Tide Fish prompt. This plugin provides prompt items that display Weather, Moon Phase, Ocean Tides, and GitHub data without slowing down your shell.
- Asynchronous: Fetches data in the background to keep your prompt fast.
- Efficient: With the default weather provider (Open-Meteo), weather is fetched in the background; moon uses a separate request when needed.
- Modular: Provides independent prompt items. Use only the ones you want.
- Configurable: Easily customize formats, units, location, and refresh rates.
- Helpful: Provides succinct weather data, moon phase data, GitHub stats, or if you really want to lean into the maritime theme, tide data.
- Install the plugin:
fisher install MrBasa/TideReport@v1 - In an interactive session you are asked whether to run the install wizard or use defaults. Use defaults to add the default prompt items (github, weather, moon) without prompts; run the wizard to choose units (metric/US), which items to add, weather format and location, etc. The wizard first asks metric or US (
tide_report_units), then shows a single-line preview of all items and, for each item (GitHub, Weather, Moon, Tide), a sample before asking whether to add it. If you add weather, you can pick a format preset and set location (IP-based or city/postal/coordinates validated via Open-Meteo). - The installer runs
tide reloadwhen Tide is available, so your prompt updates immediately. If it doesn’t, runtide reloador open a new terminal. - If weather shows as unavailable at first, the plugin may still be detecting your location in the background; wait a moment or set weather location manually.
curl: Required by theweather,moon, andtidemodules to fetch data.gh: The GitHub CLI. Required by thegithubmodule. You must be authenticated (gh auth login).jq: Required by all modules (github,tide,weather,moon) for parsing JSON data.- The latest version of Fish.
- Fisher plugin manager.
- A Nerd Font (optional, for icons).
Install with Fisher:
fisher install MrBasa/TideReport@v1Both fisher install and fisher update run the same install logic. In an interactive session you are asked whether to run the install wizard or use defaults. Use defaults to add the default prompt items (github, weather, moon) without the wizard; run the wizard to choose units, which items to add, weather format and location, etc. Non-interactive installs and updates (e.g. in CI) always use defaults: no prompt, no wizard. When install or update completes, the plugin runs tide reload (if the Tide prompt is installed) so your prompt refreshes immediately.
You can add MrBasa/TideReport@v1 to ~/.config/fish/fish_plugins and run fisher update; this is the recommended workflow when using a dotconfig manager. After fisher update, the same interactive prompt (wizard or use defaults) appears when the session is interactive.
See the Fisher and Tide documentation for more details on installing plugins.
If the installer did not run (e.g. prompt items never appeared after install) or you see odd behavior after repeated installs/uninstalls, do a clean reinstall:
- Remove the plugin:
fisher remove MrBasa/TideReport(or the path you used, e.g.fisher remove /path/to/TideReport). The uninstaller runstide reloadwhen Tide is available so the prompt updates without the TideReport items. - Optionally start a new Fish session so universals are reloaded.
- Install again:
fisher install MrBasa/TideReport@v1(or your path). The installer will runtide reloadwhen done.
If the installer never ran (e.g. you installed non-interactively), run fisher update in an interactive session and choose "run wizard" or "use defaults" to apply configuration and add prompt items.
github: Displays stars, forks, watchers, issues, and PRs for the currentghrepo, and optionally the latest CI run status for the current branch.weather: Displays the current weather (from Open-Meteo or wttr.in).moon: Displays the current moon phase (from a local offline model by default, or wttr.in when moon provider is wttr).tide: Displays the next high/low tide from NOAA (US-based).
After the install wizard (or on a non-interactive install), weather, moon, and github are added by default; tide is not. To add tide or change the order of items, edit the Tide prompt lists and reload:
set -Ua tide_right_prompt_items tide
tide reloadIf you manage these in config.fish with set -g, install and uninstall will show a message with the updated list so you can sync; you can keep using either universal or global.
Set any of the following variables universally or add them to your config.fish to override defaults.
To keep your prompt fast, this plugin fetches data in the background and relies on cached data. This is done to prevent slow network requests from blocking your shell. Background fetch jobs are disowned so the shell does not wait for them when drawing the prompt (avoiding a 3–6 second delay on new shells when cache is empty or expired).
All file-based caches are stored in ~/.cache/tide-report/.
These modules use an asynchronous, file-based caching system with two timers:
- Refresh (
..._refresh_seconds): This is the "stale" timer. If you load your prompt and the cached data is older than this value, the prompt will show the stale data and trigger a fetch in the background. Your prompt is not blocked. - Expire (
..._expire_seconds): This is the "invalid" timer. If the cached data is older than this value (or doesn't exist), the prompt will show the unavailable text (e.g.,🌊) and trigger a background fetch.
This means it is expected behavior to see the "unavailable" text for a few seconds when the cache is empty or has expired.
With the wttr weather provider, one API call fills both weather and moon. With Open-Meteo (the default), weather and moon are independent. The moon item uses a local, offline lunar phase model by default, or wttr.in when tide_report_moon_provider is set to wttr.
The github module caches repo stats and (when CI is enabled) workflow run status in ~/.cache/tide-report/github/. Repo data is stored per repository; CI data is stored per repository and branch (e.g. Owner-Repo-main-ci.json).
- Repo and CI data are fetched in the background when the cache is missing or older than their refresh timers. The prompt is never blocked.
- When Show CI status is enabled, the item shows the latest GitHub Actions workflow run for the current branch (✓ pass, ✗ fail, ⋯ pending), using
gh run list.
These settings apply to all modules in this plugin.
| Variable | Description | Default |
|---|---|---|
tide_report_service_timeout_millis |
Timeout for all web requests, in milliseconds. | 6000 |
tide_report_wttr_url |
URL for wttr.in, used for weather (wttr) and moon. | https://wttr.in |
tide_report_weather_provider |
Weather backend: wttr or openmeteo. |
openmeteo |
tide_report_units |
Units for weather and tide: m (Metric), u (USCS) |
m |
tide_time_format |
Time format string for Tide Prompt times (e.g. "%H:%M"). |
From Tide |
tide_report_log_expected |
Set to 0, false, or no to disable diagnostic logging. |
1 |
Expected issues (missing dependency, bad GitHub credentials, service API unavailable, invalid weather location, etc.) are written to a log file so the prompt is never delayed by I/O.
- Location:
$XDG_STATE_HOME/tide-report/tide-report.log(or~/.local/state/tide-report/tide-report.logifXDG_STATE_HOMEis not set). - When to look: If a prompt item consistently shows its "unavailable" text (e.g. … or 🌊…), examine this log file for the cause. Log lines are tab-separated: timestamp, TideReport version, category (
dependency,github,weather,tide,moon), and message. Disable logging by settingtide_report_log_expectedto0,false, orno.
Requires gh CLI to be installed and authenticated.
The module displays stats for the current repository, with icons you can customize.
| Symbol | Meaning |
|---|---|
★ (Stars) |
Total stargazer count |
⑂ (Forks) |
Total fork count |
(Watchers) |
Total watcher count |
! (Issues) |
Open issue count |
PR (Pull Requests) |
Open PR count |
✓ / ✗ / ⋯ (CI) |
Latest workflow run: pass / fail / pending |
!auth (Error) |
gh CLI is not authenticated |
| Variable | Description | Default |
|---|---|---|
tide_github_color |
Prompt item color | white |
tide_github_bg_color |
Prompt item background color | (theme default) |
tide_report_github_icon_stars |
Icon for stars. | ★ |
tide_report_github_icon_forks |
Icon for forks. | ⑂ |
tide_report_github_icon_watchers |
Icon for watchers. | |
tide_report_github_icon_issues |
Icon for open issues. | ! |
tide_report_github_icon_prs |
Icon for open pull requests. | PR |
tide_report_github_color_stars |
Color for stargazers. | yellow |
tide_report_github_color_forks |
Color for forks (defaults to ..._color_stars). |
yellow |
tide_report_github_color_watchers |
Color for watchers (defaults to ..._color_stars). |
yellow |
tide_report_github_color_issues |
Color for issues (defaults to ..._color_stars). |
yellow |
tide_report_github_color_prs |
Color for PRs (defaults to ..._color_stars). |
yellow |
tide_report_github_refresh_seconds |
GitHub data cache time for a given repository. | 30 |
tide_report_github_show_ci |
Whether to show CI status (latest workflow run) in the GitHub item. | true |
tide_report_github_icon_ci_pass |
Icon when the latest workflow run succeeded. | ✔ |
tide_report_github_icon_ci_fail |
Icon when the latest workflow run failed or was cancelled. | ✗ |
tide_report_github_icon_ci_pending |
Icon when the workflow is queued or in progress. | ⋯ |
tide_report_github_color_ci_pass |
Color for the CI pass icon. | green |
tide_report_github_color_ci_fail |
Color for the CI fail icon. | red |
tide_report_github_color_ci_pending |
Color for the CI pending icon. | yellow |
tide_report_github_ci_refresh_seconds |
How long to cache CI status before refetching. | 60 |
tide_report_github_unavailable_text |
Text to display when GitHub data is not available. | … |
tide_report_github_unavailable_color |
Color for the unavailable text. | red |
This module requires jq for parsing JSON.
The weather format is a string with custom specifiers. When you add the weather item in the install wizard, you can choose one of three presets: concise (emoji + temp), medium (emoji + temp + wind), or detailed (thermometer + temp, feels-like in parentheses, humidity + wind).
| Specifier | Description | Example |
|---|---|---|
%t |
Temperature (with + or - sign) |
+10° |
%C |
Condition text | Clear |
%c |
Condition emoji | ☀️ |
%w |
Wind speed and unit | 15km/h |
%d |
Wind direction arrow (direction wind is blowing to; matches wttr.in) | ⬇ etc. |
%h |
Humidity | 80% |
%f |
'Feels like' temperature | +8° |
%u |
UV Index | 42 |
%S |
Sunrise time | 06:37 |
%s |
Sunset time | 19:46 |
| Variable | Description | Default |
|---|---|---|
tide_weather_color |
Prompt item color | (theme default) |
tide_weather_bg_color |
Prompt item background color | (theme default) |
tide_report_weather_format |
Format string (see table above). | "%c %t %d%w" |
tide_report_weather_symbol_color |
Color for symbols in weather output. | white |
tide_report_weather_location |
Location for weather. See Weather location below. | "" |
tide_report_weather_refresh_seconds |
How old data can be before a background refresh is triggered. | 300 |
tide_report_weather_expire_seconds |
How old data can be before it's considered invalid. | 900 |
tide_report_weather_language |
Two-letter language code (e.g., de, fr, zh-cn). |
en |
tide_report_weather_unavailable_text |
Text to display when weather data is not available. | … |
tide_report_weather_unavailable_color |
Color for the unavailable text. | red |
tide_report_weather_location controls where weather is fetched for. The install wizard can configure it (validated via Open-Meteo). Valid values depend on the weather provider (tide_report_weather_provider). Both providers accept GPS coordinates as latitude,longitude (e.g. -78.46,106.79). No spaces.
When provider is openmeteo (default):
- Empty string
""(default): Your location is detected from your IP in the background and cached per shell session (file under~/.cache/tide-report/). A new terminal in a new place will detect again. No need to set anything for IP-based weather. - Place name or postal code: The value is sent to the Open-Meteo Geocoding API. Use a city name, region, or postal code (e.g.
Berlin,London,90210). At least three characters are recommended for fuzzy matching. - GPS coordinates: Use
latitude,longitudeto skip geocoding.
When provider is wttr:
- Empty string
"": wttr.in uses your IP address to guess your location. - City or place name: Use a single word or hyphenated name (e.g.
Paris,Saint-Petersburg,New-York). Unicode is supported. For spaces use hyphens or+(e.g.Eiffel+tower). - 3-letter airport code: e.g.
muc,lhr,jfk. - Postal or area code: e.g.
90210,94107. - GPS coordinates:
latitude,longitude(e.g.-78.46,106.79). - Domain name: Prefix with
@(e.g.@stackoverflow.com) for location derived from the domain.
This module requires jq. It uses its own cache file (~/.cache/tide-report/moon.json). Moon phase is computed by a local, offline astronomical model by default (inspired by the Sun and Moon formulas from SunCalc), or fetched from wttr.in when tide_report_moon_provider is wttr. When both moon and weather use wttr, one request fills both caches. It displays the moon phase emoji.
| Variable | Description | Default |
|---|---|---|
tide_moon_color |
Prompt item color | (theme default) |
tide_moon_bg_color |
Prompt item background color | (theme default) |
tide_report_moon_provider |
Moon backend: local (offline model) or wttr. |
local |
tide_report_moon_refresh_seconds |
How old data can be before a background refresh is triggered. | 14400 |
tide_report_moon_expire_seconds |
How old data can be before it's considered invalid. | 28800 |
tide_report_moon_unavailable_text |
Text to display when moon data is not available. | … |
tide_report_moon_unavailable_color |
Color for the unavailable text. | red |
This module requires jq and you must set a Station ID (default Boston).
To find your nearest station, use the NOAA Tides and Currents Map. Search for your location (e.g., by city or ZIP code), click on a nearby station icon on the map, and copy the Station ID number. Ensure that the station has high and low tide predictions available.
| Variable | Description | Default |
|---|---|---|
tide_tide_color |
Prompt item color | 0087AF |
tide_tide_bg_color |
Prompt item background color | (theme default) |
tide_report_tide_station_id |
Required. The NOAA station ID (e.g., 8443970 for Boston). |
"8443970" |
tide_report_tide_refresh_seconds |
How old data can be before a background refresh is triggered. | 14400 |
tide_report_tide_expire_seconds |
How old data can be before it's considered invalid. | 28800 |
tide_report_tide_symbol_high |
Symbol to show for an upcoming high tide. | ⇞ |
tide_report_tide_symbol_low |
Symbol to show for an upcoming low tide. | ⇟ |
tide_report_tide_symbol_color |
Color for the high/low tide symbol. | white |
tide_report_tide_unavailable_text |
Text to display when tide data is not available. | 🌊… |
tide_report_tide_unavailable_color |
Color for the unavailable text. | red |
tide_report_tide_show_level |
Set to "true" to show the height of the next tide. |
"true" |
The project uses Fishtape for unit and integration tests. Install it with Fisher:
CI: GitHub Actions runs the test suite on Ubuntu (GNU date) and macOS (BSD date) on every push and PR so that date-formatting and cache logic stay compatible with both.
fisher install jorgebucaran/fishtapeFrom the repo root, run all tests:
fishtape test/unit/*.fish test/integration/*.fishRun only unit tests or only integration tests:
fishtape test/unit/*.fish
fishtape test/integration/*.fishPre-push hook (gated check-in): To run the test suite automatically before every push to main or master (and block the push if tests fail), install the pre-push hook from the repo root:
cp scripts/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-pushYou need Fish and Fishtape available (same as running the tests manually). The hook only runs when the push updates main or master; pushes to other branches are not gated.
Tests use fixture data under test/fixtures/ and do not require network access or Tide to be installed.
- Weather shows as unavailable: With the default provider (Open-Meteo) and empty location, the plugin detects your location from your IP in the background. Wait a few seconds for the first fetch to complete, or open a new terminal to trigger a fresh lookup. You can also set weather location explicitly.
- Jorge Bucaran and Ilan Cosman for making Fisher and Tide.
- Moby Dick, the sweet air of the ocean breeze, and the gentle lullaby the sea sings before she breaks you on the rocks.
- NOAA - we'll miss them when they're gone... 🇺🇸😢
- Igor Chubin and all the contributors/sponsors of wttr.in.
- Vladimir Agafonkin for the SunCalc library, whose public moon phase formulas inspired the local lunar model used here.
