hermes-agent/skills/productivity/maps/SKILL.md
Teknium 4a2198bf51
fix: Windows MCP PATHEXT resolution + python3 -> python in cross-platform skills (#84429)
Two Windows agent-loop friction fixes:

1. tools/mcp_tool.py (#56536): shutil.which(cmd, path=env_path) reads
   executable extensions from the PARENT process PATHEXT, not the MCP
   subprocess env — a stdio MCP config supplying both PATH and PATHEXT
   could fail to resolve a command its own env can locate, and startup
   then got a bare command name. On Windows, when the first which() call
   misses and the config env carries PATHEXT (any key casing), retry the
   resolution with the config's PATHEXT temporarily applied.

2. skills/ + optional-skills/ (#50606): 42 SKILL.md files that declare
   platforms: [.., windows] used python3 in their command examples.
   python3 does not exist on native Windows (the toolchain probe in the
   system prompt reports python3=missing), so every copy-pasted example
   burned a failed agent turn before self-correction. Replaced the
   command word python3 -> python (python3-config / python3.x version
   strings untouched). python is the spelling that exists in every
   Hermes-managed environment (Windows native, uv-managed venvs on all
   three OSes); agents on POSIX hosts additionally see the probed
   toolchain line and adapt either way.
2026-08-12 02:43:28 -07:00

6.5 KiB

name description version author license platforms metadata
maps Geocode, POIs, routes, timezones via OpenStreetMap/OSRM. 1.2.0 Mibayy MIT
linux
macos
windows
hermes
tags category requires_toolsets supersedes
maps
geocoding
places
routing
distance
directions
nearby
location
openstreetmap
nominatim
overpass
osrm
productivity
terminal
find-nearby

Maps Skill

Location intelligence using free, open data sources. 8 commands, 44 POI categories, zero dependencies (Python stdlib only), no API key required.

Data sources: OpenStreetMap/Nominatim, Overpass API, OSRM, TimeAPI.io.

This skill supersedes the old find-nearby skill — all of find-nearby's functionality is covered by the nearby command below, with the same --near "<place>" shortcut and multi-category support.

When to Use

  • User sends a Telegram location pin (latitude/longitude in the message) → nearby
  • User wants coordinates for a place name → search
  • User has coordinates and wants the address → reverse
  • User asks for nearby restaurants, hospitals, pharmacies, hotels, etc. → nearby
  • User wants driving/walking/cycling distance or travel time → distance
  • User wants turn-by-turn directions between two places → directions
  • User wants timezone information for a location → timezone
  • User wants to search for POIs within a geographic area → area + bbox

Prerequisites

Python 3.8+ (stdlib only — no pip installs needed).

Script path: ~/.hermes/skills/maps/scripts/maps_client.py

Commands

MAPS=~/.hermes/skills/maps/scripts/maps_client.py

search — Geocode a place name

python $MAPS search "Eiffel Tower"
python $MAPS search "1600 Pennsylvania Ave, Washington DC"

Returns: lat, lon, display name, type, bounding box, importance score.

reverse — Coordinates to address

python $MAPS reverse 48.8584 2.2945

Returns: full address breakdown (street, city, state, country, postcode).

nearby — Find places by category

# By coordinates (from a Telegram location pin, for example)
python $MAPS nearby 48.8584 2.2945 restaurant --limit 10
python $MAPS nearby 40.7128 -74.0060 hospital --radius 2000

# By address / city / zip / landmark — --near auto-geocodes
python $MAPS nearby --near "Times Square, New York" --category cafe
python $MAPS nearby --near "90210" --category pharmacy

# Multiple categories merged into one query
python $MAPS nearby --near "downtown austin" --category restaurant --category bar --limit 10

46 categories: restaurant, cafe, bar, hospital, pharmacy, hotel, guest_house, camp_site, supermarket, atm, gas_station, parking, museum, park, school, university, bank, police, fire_station, library, airport, train_station, bus_stop, church, mosque, synagogue, dentist, doctor, cinema, theatre, gym, swimming_pool, post_office, convenience_store, bakery, bookshop, laundry, car_wash, car_rental, bicycle_rental, taxi, veterinary, zoo, playground, stadium, nightclub.

Each result includes: name, address, lat/lon, distance_m, maps_url (clickable Google Maps link), directions_url (Google Maps directions from the search point), and promoted tags when available — cuisine, hours (opening_hours), phone, website.

distance — Travel distance and time

python $MAPS distance "Paris" --to "Lyon"
python $MAPS distance "New York" --to "Boston" --mode driving
python $MAPS distance "Big Ben" --to "Tower Bridge" --mode walking

Modes: driving (default), walking, cycling. Returns road distance, duration, and straight-line distance for comparison.

directions — Turn-by-turn navigation

python $MAPS directions "Eiffel Tower" --to "Louvre Museum" --mode walking
python $MAPS directions "JFK Airport" --to "Times Square" --mode driving

Returns numbered steps with instruction, distance, duration, road name, and maneuver type (turn, depart, arrive, etc.).

timezone — Timezone for coordinates

python $MAPS timezone 48.8584 2.2945
python $MAPS timezone 35.6762 139.6503

Returns timezone name, UTC offset, and current local time.

area — Bounding box and area for a place

python $MAPS area "Manhattan, New York"
python $MAPS area "London"

Returns bounding box coordinates, width/height in km, and approximate area. Useful as input for the bbox command.

bbox — Search within a bounding box

python $MAPS bbox 40.75 -74.00 40.77 -73.98 restaurant --limit 20

Finds POIs within a geographic rectangle. Use area first to get the bounding box coordinates for a named place.

Working With Telegram Location Pins

When a user sends a location pin, the message contains latitude: and longitude: fields. Extract those and pass them straight to nearby:

# User sent a pin at 36.17, -115.14 and asked "find cafes nearby"
python $MAPS nearby 36.17 -115.14 cafe --radius 1500

Present results as a numbered list with names, distances, and the maps_url field so the user gets a tap-to-open link in chat. For "open now?" questions, check the hours field; if missing or unclear, verify with web_search since OSM hours are community-maintained and not always current.

Workflow Examples

"Find Italian restaurants near the Colosseum":

  1. nearby --near "Colosseum Rome" --category restaurant --radius 500 — one command, auto-geocoded

"What's near this location pin they sent?":

  1. Extract lat/lon from the Telegram message
  2. nearby LAT LON cafe --radius 1500

"How do I walk from hotel to conference center?":

  1. directions "Hotel Name" --to "Conference Center" --mode walking

"What restaurants are in downtown Seattle?":

  1. area "Downtown Seattle" → get bounding box
  2. bbox S W N E restaurant --limit 30

Pitfalls

  • Nominatim ToS: max 1 req/s (handled automatically by the script)
  • nearby requires lat/lon OR --near "<address>" — one of the two is needed
  • OSRM routing coverage is best for Europe and North America
  • Overpass API can be slow during peak hours; the script automatically falls back between mirrors (overpass-api.de → overpass.kumi.systems)
  • distance and directions use --to flag for the destination (not positional)
  • If a zip code alone gives ambiguous results globally, include country/state

Verification

python ~/.hermes/skills/maps/scripts/maps_client.py search "Statue of Liberty"
# Should return lat ~40.689, lon ~-74.044

python ~/.hermes/skills/maps/scripts/maps_client.py nearby --near "Times Square" --category restaurant --limit 3
# Should return a list of restaurants within ~500m of Times Square