{"id":50299633,"url":"https://github.com/statico/blorkobot","last_synced_at":"2026-05-28T11:32:22.502Z","repository":{"id":358105695,"uuid":"1239911313","full_name":"statico/blorkobot","owner":"statico","description":"blorkobot","archived":false,"fork":false,"pushed_at":"2026-05-15T18:01:17.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-15T20:44:47.374Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/statico.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T15:13:23.000Z","updated_at":"2026-05-15T18:01:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/statico/blorkobot","commit_stats":null,"previous_names":["statico/blorkobot"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/statico/blorkobot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fblorkobot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fblorkobot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fblorkobot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fblorkobot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statico","download_url":"https://codeload.github.com/statico/blorkobot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statico%2Fblorkobot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33607334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-28T11:32:22.404Z","updated_at":"2026-05-28T11:32:22.493Z","avatar_url":"https://github.com/statico.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BlorkoBot\n\nBlorkoBot is an unofficial bot for [MeshCore](https://github.com/meshcore-dev/MeshCore), the mesh radio protocol. It's a Python \"fanout\" plugin for [Remote Terminal for MeshCore](https://github.com/nicholasgasior/Remote-Terminal-for-MeshCore) plus a Node.js alert server, originally built for Bay Area MeshCore by Blorko and 100% coded with [Claude Code](https://claude.ai/code).\n\nIt responds in channels like **#bot**, **#test**, **#path**, **DMs**, and select topic channels (**#weather**, **#earthquake**, **#fire**, **#space**).\n\n\u003e **Note:** This is **not** the exact version of BlorkoBot running on [bayareameshcore.org](https://bayareameshcore.org). API keys, channel keys, content filter words, and a few region-specific bits have been blanked out so the source can be public. You'll need to fill these in for your own deployment. See [CLAUDE.md](./CLAUDE.md) for setup notes.\n\n## Files\n\n- **`bot.py`** — Fanout plugin for Remote Terminal. Handles all `!` commands and DM path replies.\n- **`server.ts`** — Long-running Node.js server. Polls external services (USGS quakes, NWS weather alerts, CAL FIRE, NOAA SWPC, PG\u0026E outages, RSS) and posts to MeshCore channels. Also logs telemetry.\n\n## Getting Started\n\nSend `!help` to BlorkoBot in #bot, #test, or a DM to see available commands. Commands start with `!`.\n\nSend `!dm` in a channel and BlorkoBot will send you a direct message with path/hop info — useful for testing your mesh connectivity. In DMs, BlorkoBot also replies with path/hop information for any message.\n\n## Commands\n\n### Info \u0026 Navigation\n\n| Command | Description |\n|---------|-------------|\n| `!help` | Show page 1 of commands |\n| `!help2` / `!help3` / `!help4` | Subsequent help pages |\n| `!docs` | Link to full documentation |\n| `!about` | About BlorkoBot |\n| `!channels` | List known, popular channels |\n| `!path` / `!ping` / `test` / `!test` | Show hop count, path, and one-way transit time to BlorkoBot |\n| `!pathx` | Extended path: each hop's repeater name + lat/lon (aliases: `!longpath`, `!bigpath`). `?` marks ambiguous prefix matches. Disambiguation algorithm adapted from [CoreScope](https://github.com/Kpa-clawbot/CoreScope) by Kp |\n| `!pathall` / `!patha` | Wait ~8s and list every path the message arrived via |\n| `!dm` | BlorkoBot sends you a DM with path/hop info |\n| `!2byte` | Link to 2-byte prefix info + progress bar |\n\n### Weather \u0026 Environment\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!weather \u003clocation\u003e` | Current weather + UV index (Fahrenheit). Alias: `!w` | [wttr.in](https://wttr.in) |\n| `!wc \u003clocation\u003e` | Current weather + UV index (Celsius) | [wttr.in](https://wttr.in) |\n| `!forecast \u003clocation\u003e` | 3-day forecast (Fahrenheit). Alias: `!fc` | [wttr.in](https://wttr.in) |\n| `!fcc \u003clocation\u003e` | 3-day forecast (Celsius) | [wttr.in](https://wttr.in) |\n| `!sun \u003clocation\u003e` | Sunrise and sunset times | [wttr.in](https://wttr.in) |\n| `!moon` | Current moon phase and illumination | Local calculation |\n| `!alerts \u003cstate\u003e` | Active NWS weather alerts (2-letter state code) | [NWS API](https://api.weather.gov) |\n| `!aqi \u003clocation\u003e` | Air quality index (US AQI + PM2.5) | [Open-Meteo](https://open-meteo.com) |\n| `!pollen \u003clocation\u003e` | Pollen count by type and level | [Open-Meteo](https://open-meteo.com) |\n\n### Tides, Ocean \u0026 Rivers\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!tide \u003cstation\u003e` | NOAA tide predictions (name or station ID). Alias: `!surf` | [NOAA Tides \u0026 Currents](https://tidesandcurrents.noaa.gov) |\n| `!wave \u003clocation\u003e` | Ocean wave height, period, and direction | [Open-Meteo Marine](https://open-meteo.com) |\n| `!river \u003cname or site#\u003e` | Real-time river/stream flow and gauge height (CA) | [USGS Water Services](https://waterservices.usgs.gov) |\n\n### Science \u0026 Space\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!quake [count] [mag] [location]` | Earthquakes in CA/NV (default) or near a location | [USGS Earthquake Hazards](https://earthquake.usgs.gov) |\n| `!fire` | Active CA wildfires (top 3 by size). Aliases: `!fires`, `!wildfire` | [CAL FIRE](https://www.fire.ca.gov/incidents) |\n| `!511 [route]` | Recent Bay Area traffic incidents or construction by highway | [511 SF Bay](https://511.org) |\n| `!space` | Space weather: Kp index, solar wind, Bz, solar flux. Alias: `!solar` | [NOAA SWPC](https://www.swpc.noaa.gov) |\n| `!swx` | Active space weather warnings/watches | [NOAA SWPC](https://www.swpc.noaa.gov) |\n| `!flare` | Recent solar flares (X-ray class) | [NOAA SWPC](https://www.swpc.noaa.gov) |\n| `!iss` | Current ISS position | [Open Notify](http://open-notify.org) |\n| `!iss \u003clocation\u003e` | Upcoming visible ISS passes (min 20 deg elevation) | [N2YO](https://www.n2yo.com) |\n| `!neo` | Near-Earth objects tracked today. Alias: `!asteroid` | [NASA NEO API](https://api.nasa.gov) |\n| `!hf` | HF radio propagation conditions + solar indices | [hamqsl.com](https://www.hamqsl.com) |\n| `!apod` | NASA Astronomy Picture of the Day. Alias: `!nasa` | [NASA APOD](https://api.nasa.gov) |\n\n### Utilities\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!time \u003ccity\u003e` | Current time in any city | [wttr.in](https://wttr.in) |\n| `!convert \u003cval\u003e \u003cfrom\u003e \u003cto\u003e` | Unit conversion (mi/km, ft/m, in/cm, lb/kg, oz/g, gal/l, mph/kph, nmi, f/c) | Local calculation |\n| `!zip \u003czipcode\u003e` | Zip code to city, state, and coordinates | [Zippopotam.us](https://api.zippopotam.us) |\n| `!who \u003cprefix\u003e` | Look up repeaters by hex prefix (e.g. `!who 77`) | Local |\n| `!advert` | Trigger a flood advertisement (announce presence on mesh) | Local |\n| `!stats` | Mesh network stats: nodes, repeaters, packets, noise floor, repeater hash widths | Local |\n| `!define \u003cword\u003e` | Dictionary definition | [Free Dictionary API](https://dictionaryapi.dev) |\n| `!wiki \u003ctopic\u003e` | Wikipedia summary | [Wikipedia REST API](https://en.wikipedia.org/api/rest_v1/) |\n| `!country \u003cname\u003e` | Country info: capital, population, region, languages | [REST Countries](https://restcountries.com) |\n\n### Finance\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!stock \u003csymbol\u003e` | Stock price and daily change | [Yahoo Finance](https://finance.yahoo.com) |\n| `!crypto \u003ccoin\u003e` | Crypto price (btc, eth, sol, doge, …) | [CoinGecko](https://www.coingecko.com) |\n\n### Sports\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!score \u003cteam\u003e` | Bay Area sports score (giants, warriors, 49ers, sharks, quakes, roots, as) | [ESPN](https://www.espn.com) |\n\n### Aviation\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!flight \u003cnumber\u003e` | Flight status: route, gate/terminal, times, delay, status. Alias: `!flights` | [AeroDataBox](https://aerodatabox.com) |\n| `!delays [airport]` | FAA ground stops \u0026 delays. No arg = SFO/OAK/SJC summary | [FAA NAS Status](https://nasstatus.faa.gov) |\n| `!sky [location]` | Non-airline aircraft overhead: helicopters, military, blimps, balloons | [ADSB.lol](https://adsb.lol) |\n| `!mil [location]` | Military aircraft currently airborne. Alias: `!military` | [ADSB.lol](https://adsb.lol) |\n| `!blimp [location]` | Lighter-than-air craft. Alias: `!blimps` | [ADSB.lol](https://adsb.lol) |\n| `!tfr` | Bay Area temporary flight restrictions. Alias: `!temp` | [FAA TFR](https://tfr.faa.gov) |\n\n### Infrastructure\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!power` | PG\u0026E Bay Area outages affecting 500+ customers. Alias: `!outage` | [PG\u0026E](https://www.pge.com) |\n\n### Fun \u0026 Games\n\n| Command | Description | Source |\n|---------|-------------|--------|\n| `!ai \u003cquestion\u003e` | Ask the AI a question | [Groq](https://groq.com) |\n| `!sonnet \u003csubject\u003e` | Short Shakespearean sonnet about the subject | [Groq](https://groq.com) |\n| `!haiku \u003csubject\u003e` | Haiku (5/7/5) about the subject | [Groq](https://groq.com) |\n| `!trivia [easy\\|medium\\|hard]` | Trivia question — answer with A/B/C/D or `!guess` | [Open Trivia DB](https://opentdb.com) |\n| `!guess \u003cletter\u003e` / `!answer \u003cletter\u003e` | Answer the active trivia question | — |\n| `!leaderboard` | Top 10 trivia scorers. Alias: `!lb` | Local |\n| `!chess` | Start a new chess game vs the bot | [chess-api.com](https://chess-api.com) |\n| `!move \u003cuci\u003e` | Make a chess move in UCI format, e.g. `!move e2e4` | — |\n| `!board` | Show the current chess board and recent moves | — |\n| `!resign` | Resign the current chess game | — |\n| `!elo [800-2400]` | Show or set the bot's chess difficulty | — |\n| `!otd` | Random historical event on this day. Alias: `!today` | [Wikipedia](https://en.wikipedia.org) |\n| `!8ball [question]` | Magic 8-Ball | Local |\n| `!joke [search]` | Random joke | [JokeAPI](https://v2.jokeapi.dev) |\n| `!dadjoke` | Random dad joke | [icanhazdadjoke](https://icanhazdadjoke.com) |\n| `!riddle` | Random riddle (with answer) | [Riddles API](https://riddles-api.vercel.app) |\n| `!quote` | Inspirational quote. Alias: `!inspire` | [ZenQuotes](https://zenquotes.io) |\n| `!advice` | Random advice | [Advice Slip](https://api.adviceslip.com) |\n| `!fact` | Random fun fact | [Useless Facts](https://uselessfacts.jsph.pl) |\n| `!catfact` | Random cat fact. Alias: `!cat` | [Cat Facts](https://catfact.ninja) |\n| `!cocktail` | Random cocktail recipe. Alias: `!drink` | [TheCocktailDB](https://www.thecocktaildb.com) |\n| `!futurama` | Random Futurama quote | [Morbotron](https://morbotron.com) |\n| `!simpsons` | Random Simpsons quote | [Frinkiac](https://frinkiac.com) |\n\n### Key-Value Store\n\nA shared notepad — anyone can set and read values.\n\n| Command | Description |\n|---------|-------------|\n| `!set \u003ckey\u003e \u003cvalue\u003e` | Store a value (32 char key, 200 char value max) |\n| `!get \u003ckey\u003e` | Retrieve a stored value |\n| `!del \u003ckey\u003e` | Delete a stored value |\n\nUp to 100 keys total.\n\n## Automatic Alerts\n\nThe `server.ts` companion process posts automatic alerts to dedicated channels:\n\n- **#earthquake** — Earthquakes M2.5+ in a configurable bounding box (from [USGS](https://earthquake.usgs.gov))\n- **#weather** — NWS weather alerts for configured zones (from [NWS API](https://api.weather.gov)). Same event types are rate-limited to avoid spam.\n- **#fire** — Active California wildfires (from [CAL FIRE](https://www.fire.ca.gov/incidents))\n- **#space** — Solar flares (M-class+) and geomagnetic storms (Kp 5+) (from [NOAA SWPC](https://www.swpc.noaa.gov))\n- **#power** — PG\u0026E power outages (500+ customers) with city location (from [PG\u0026E](https://www.pge.com))\n- **#alert** — Aggregated firehose of all of the above\n- **#bot** / **#alert** — New posts from a configured RSS feed\n\nThese are pushed automatically — no commands needed. Just join the channel.\n\n## Topic Channels\n\nBlorkoBot also responds to relevant commands in topic channels:\n\n| Channel | Commands |\n|---------|----------|\n| **#weather** | `!weather` `!wc` `!forecast` `!fcc` `!sun` `!tide` `!surf` `!alerts` `!aqi` `!wave` |\n| **#earthquake** | `!quake` `!quakes` `!earthquake` `!earthquakes` |\n| **#fire** | `!fire` `!fires` `!wildfire` |\n| **#space** | `!space` `!solar` `!swx` `!flare` `!hf` |\n| **#path** | `!path` `!pathx` `!pathall` `!patha` `!longpath` `!bigpath` `!ping` `!test` `!dm` `!stats` |\n\nOnly the listed commands work in each topic channel. Use **#bot** or **#test** for the full command set.\n\n## Tips\n\n- Location-based commands require a location (e.g., `!weather sf`). Shortcuts: **\"sf\"** = San Francisco, **\"sj\"** = San Jose, **\"sfo\"** = SFO airport.\n- Messages are limited by mesh radio constraints (~120 bytes), so responses are kept short. Long responses may be split across multiple messages (up to 3).\n- In DMs, any non-command message returns path/hop info — great for testing connectivity.\n\n## Setup\n\n1. Install and run [Remote Terminal for MeshCore](https://github.com/nicholasgasior/Remote-Terminal-for-MeshCore) — it listens on `http://127.0.0.1:4042` by default.\n2. Create a fanout plugin in Remote Terminal pointing at `bot.py`, or PATCH the source in via the API (see [CLAUDE.md](./CLAUDE.md)).\n3. Fill in API keys in `bot.py` (`_N2YO_KEY`, `_BAY511_API_KEY`, `_GROQ_KEY`, `_AERODATABOX_KEY`). Commands degrade gracefully when keys are missing.\n4. Fill in the channel keys at the top of `server.ts` for the channels you want alerts posted to, and adjust `QUAKE_BBOX` and `NWS_ZONES` for your region.\n5. Run `server.ts` with `node --experimental-strip-types --env-file=.env --watch server.ts`.\n\n## License\n\n[Unlicense](https://unlicense.org) — public domain.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Fblorkobot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatico%2Fblorkobot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatico%2Fblorkobot/lists"}