picky

Picky — it picks the best stay and ride for you (Hermes plugin)

Picky is a Hermes Agent plugin that decides for you. Tell it where you are or where you're
going, and it:

Auto-picks the best place to sleep, tonight or for any dates, with a one-line why and
2–3 backups. It uses real hotels, guest houses (BnB style), hostels and apartments mapped in
OpenStreetMap, ranked by OSRM drive/walk time plus OSM facts (stars, operator, phone, 24/7).
Shows the rides available: Uber, Bolt and Lyft (depending on the region), walking when it's
short, and Maps. Each comes with a rough fare range and ETA, and Picky picks the best one.
Plans a stay for your dates: Booking.com, Airbnb, Expedia and Google Hotels links with the
check-in, check-out, guests and rooms already filled in.
Sets up the reservation: "I've set it up: Nov 12–14, 2 guests, tap Confirm on Booking.com".
You also get a ready message to WhatsApp or call the place, plus a ride there.
Never dead-ends. It never says "invalid" or "failed". When data is thin it gives its best
guess, adds worth checking yourself asap links, and offers to set up the reservation.

Safe by design. Picky never books, never pays and never asks for a card. It builds the links,
and you make the final tap on Booking.com, Airbnb, Uber or another site. It needs no API keys and
has no telemetry. Your location is used once and then released (see Privacy).

Previews

Real runs, rendered by Picky's own dark HTML report (--html).

| Tonight near Lagos airport | Reserve: Nov 12–14, 2 guests |
|---|---|
| Picky tonight near Lagos airport | Picky reservation ready |

| Stay for dates (Lekki) | Rides in London |
|---|---|
| Picky stay for dates in Lekki | Picky rides in London |

Tools

| Tool | What it does | Try saying |
|---|---|---|
| picky_tonight | Stranded mode: best place to sleep tonight near you, plus the best ride there | "I just landed at Lagos airport, nowhere to sleep, pick for me" |
| picky_stay | Stay for specific dates and guests: Best pick, backups, and date-filled booking links | "Find me a place in Lekki Nov 12–14 for 2, I'm coming from the airport" |
| picky_ride | Rides available A → B, ranked, with rough fares and ETAs | "Cheapest way from Lekki Phase 1 to the airport?" |
| picky_reserve | Prepares the reservation: one Confirm link, a summary, a message to the place, and a ride there | "Reserve it" / "Reserve the Wheatbaker on Airbnb instead" |

Options: prefer (balanced, closest, budget, comfort), guests, rooms, nights, stay_type
(hotel, guest_house, hostel, apartment…), platform for reserve (booking, airbnb, expedia,
google, website, call), and use_current_location (one-shot).

Dates can be written in plain words: tonight, tomorrow, friday, Nov 12, 12 Nov or
2026-11-12. If a date doesn't make sense (for example check-out before check-in), Picky fixes
it to the closest sensible choice and says so in a friendly way.

How Picky picks

Stays. Each stay is scored on how near it is (OSRM drive time, or walking time when it's
close), its OSM stars tag, whether it has a known operator or brand, and whether a phone or
website is listed (so you can confirm fast). Tonight, a stay tagged 24/7 gets a bonus. The
prefer option shifts the weights: budget favours hostels, guest houses and motels, comfort
favours starred hotels, and 3+ guests favours whole apartments or chalets. The why line only
uses facts Picky really has.

Rides. Regions get the apps that operate there: Nigeria, Ghana, Kenya and South Africa get
Bolt and Uber, the EU gets Bolt and Uber, the UK gets Uber and Bolt, and the US and Canada get
Uber and Lyft. Fares are a rough estimate from a small per-region rate table (base + per km +
per minute, ±25%), and ETAs use OSRM time plus a traffic buffer. Both are always labelled as
estimates, because the app shows the real price before you confirm. Bolt's rate is assumed to be
about 10% below Uber's, which is a rule of thumb, not a quote.

What each ride link does:

Get an Uber opens Uber's ride planner with pickup and dropoff set, and works in a desktop
or phone browser. Uber asks you to log in, and in some countries (the UK, for example) web
booking is switched off, so you finish in the app. open_uber_app in the data is the phone
app link.
Lyft (US and Canada only) opens the Lyft app with both ends set. On a computer, Lyft says
to use the app.
Bolt has no public prefill link. It opens Bolt's ride page and tells you the dropoff to type.

Walking becomes the Best pick when it's very short. In picky_tonight, that only happens late at
night when the walk is under 5 minutes.

Honest limits

OpenStreetMap doesn't know room prices or vacancy, so live rooms and prices are on the booking
pages. Picky says this every time.
Ride fares and ETAs are rough estimates, not quotes.
Booking.com and Airbnb open with the dates, guests and rooms filled in (checked in a real
browser). Expedia gets the same fields in its standard startDate/endDate/adults URL.
Google Hotels opens the right hotel or area with the guests set, but it ignores dates in
links, so you tap the dates once. Picky says so in the reply.
Booking.com, Expedia and Google open a search for the named place, so the place is usually
the first result. Airbnb opens the map area around it, since hotels aren't Airbnb listings.
Hotel phone numbers and websites come from OpenStreetMap volunteers, and a few may be out of date.
Data comes from shared public servers (Overpass and OSRM). When Overpass is busy, Picky
switches to Nominatim's OpenStreetMap search for named stays. If both are slow, it still
answers with live search links instead of an error.

Privacy

"My location" makes one keyless, city-level IP lookup (ipinfo.io, falling back to
ipapi.co). The location is used for that one search and then released. It is never cached,
logged or written to disk, ctx.state or plugin_data, and the raw IP is never kept.
If you ask for a ride without a pickup, Picky makes no IP lookup at all. The Uber link uses your
phone's own pickup spot.
The contacted hosts are disclosed in plugin.yaml: nominatim.openstreetmap.org (max 1 request
per second), overpass-api.de, overpass.kumi.systems, router.project-osrm.org and
routing.openstreetmap.de, plus ipinfo.io and ipapi.co only when you ask for "my location".
Booking, Airbnb, Expedia, Google, Uber, Bolt, Lyft and WhatsApp links are only built as text.
Picky never contacts those sites.

Install

hermes plugins install https://github.com/decentralpapi/picky   # or copy this folder into your Hermes plugins dir
hermes plugins enable picky
hermes plugins doctor picky

Windows step-by-step (non-coder friendly): see INSTALL-WINDOWS.md.

Local testing without Hermes:

python3 run.py tonight "Murtala Muhammed Airport"
python3 run.py stay "Lekki Phase 1, Lagos" --check-in "Nov 12" --check-out "Nov 14" --guests 2 --pickup "Murtala Muhammed Airport"
python3 run.py ride "Lekki Phase 1" "Murtala Muhammed Airport"
python3 run.py reserve "Ikoyi, Lagos" --stay Wheatbaker --check-in "Nov 12" --nights 2 --guests 2 --html reserve.html
python3 -m unittest discover -s tests      # offline, fixtures
python3 scripts/live_smoke.py              # real end-to-end run of every tool, writes live/

Files

plugin.yaml, __init__.py (register(ctx), 4 tools in the picky toolset)
picky/picker.py: dates, auto-pick scoring, rough fares and ETAs
picky/engine.py: tonight, dated stay, ride, reserve, friendly fallback
picky/sources.py: keyless OSM/OSRM adapters (allowlisted hosts) and deep-link builders
picky/render.py: friendly reply_markdown and a static dark HTML report (no scripts, no remote assets)
previews/: dark preview PNGs from real runs; live/: the raw outputs behind them

README from the reviewed commit 58501e0; it updates when the author re-pins.

About