Havan ✈️ — an autonomous flight‑deal hunting AI agent (public demo)

Havan is an AI agent you manage from Telegram. Tell it a route — or just "find me something cheap to Lisbon next month" — and it hunts the web for the cheapest fare that still has good timing, then hands back a tight, ranked shortlist with booking deep links. It compares dates and nearby airports, flags baggage and fare‑class gotchas, and is honest about price freshness. It never books — you do.

It is orchestrated by OpenClaw: OpenClaw hosts the agent, routes your Telegram messages, runs the LLM, and drives a real browser to read live flight results. Havan itself is a persona (agent-config/) plus a search‑and‑rank skill — no scraping API keys required to start.

This is a public, sanitized, dummy‑data demo. The traveler in agent-config/USER.md is fictional ("Alex Rivera", based in Berlin). Replace it with your own home airports, currency, and preferences.

---

Demo — booking a flight from Telegram

🎬 The image above is a placeholder. Replace docs/demo.gif with a real screen recording of the Telegram session (see docs/README.md). Here's the same interaction as a transcript:

You    ▸  /find cheapest BER → LIS, last week of next month, carry-on only, return

Havan  ▸  On it. Assuming 1 adult, economy, return, ±2 days flex. Shortlist (as of 14:20 CET):

         1) €78  (~$85)   Ryanair   BER 09:40 → LIS 12:25   3h45  nonstop   — cheapest
         2) €96  (~$104)  easyJet   BER 11:10 → LIS 13:55   3h45  nonstop   — best value (nicer times)
         3) €64  (~$70)   Ryanair   BER 06:15 → LIS 09:00   3h45  nonstop   — cheapest overall, early start

         Recommendation: #2 for the daytime departure; #3 only if you'll trade a 06:15 wake-up for €32.
         Flex tip: shifting return +1 day drops #2 to €88. Carry-on included on all three.
         Booking links ↓ — prices move, final price shows at checkout. I never book; tap a link to finish.

         ① skyscanner.net/…  ② easyjet.com/…  ③ ryanair.com/…

You    ▸  go with 2, but check Opodo too

Havan  ▸  Opodo has #2 at €91 all-in, but a €15 OTA service fee and stricter changes — booking direct
         on easyJet (€96) is safer for a carry-on return. Direct link: easyjet.com/…

---

What it does

• Hunts deals across Google Flights / Skyscanner and an OTA (e.g. Opodo / Kiwi), cross‑checking aggregators when a fare looks suspiciously low.
• Optimizes for value, not just price — civilised departure/arrival hours, no sub‑60‑minute layovers, no brutal red‑eyes unless the saving is worth it and you accept the trade.
• Presents a ranked shortlist (3–5): price (home currency + USD), airline, local dep→arr, duration, stops + layover, and a one‑line why (cheapest / best value / fastest), then a recommendation.
• Flags savings & caveats: flexible‑date and nearby‑airport options, baggage and basic‑economy traps.
• Hands you booking deep links — it never enters payment details or purchases anything.

Architecture

You drive Havan from Telegram; OpenClaw orchestrates the agent and brokers every search.

flowchart LR
    U["You<br/>(Telegram)"]:::user

    subgraph OC["OpenClaw gateway (orchestration)"]
        direction TB
        CH["Telegram channel<br/>(route + replies)"]:::oc
        AG["Havan agent<br/>(LLM + flight-finder skill)"]:::oc
        CH <--> AG
    end

    subgraph TL["Search tools"]
        direction TB
        BR["browser tool<br/>(Google Flights / Skyscanner / OTA)"]:::tool
        WF["web_fetch<br/>(confirm price / link)"]:::tool
        API["flight API (optional)<br/>(Amadeus / Kiwi)"]:::tool
    end

    GF["Flight sites<br/>& aggregators"]:::ext

    U -- "find me a flight / route + dates" --> CH
    AG -- "search live results" --> BR --> GF
    AG -- "verify a fare" --> WF --> GF
    AG -. "structured results" .-> API
    AG -- "ranked shortlist + booking links" --> CH --> U

    classDef user fill:#dbeafe,stroke:#60a5fa,color:#1e3a8a
    classDef oc   fill:#e0e7ff,stroke:#818cf8,color:#3730a3
    classDef tool fill:#cffafe,stroke:#22d3ee,color:#155e75
    classDef ext  fill:#fef3c7,stroke:#fbbf24,color:#92400e

    style OC fill:#f8fafc,stroke:#e2e8f0,color:#475569
    style TL fill:#f8fafc,stroke:#e2e8f0,color:#475569
    linkStyle default stroke:#94a3b8,stroke-width:1.5px

Loading

Flow: you DM a route → OpenClaw routes it to the Havan agent → the agent searches live results via the browser (and optionally a flight API) → it ranks the best value options → the shortlist + booking links come back to your Telegram. You make the booking.

Repository layout

havan/
├─ README.md
├─ .env.example                      # optional: flight API keys + model
├─ .gitignore
└─ agent-config/                     # the agent's persona + behavior (for an OpenClaw gateway)
   ├─ IDENTITY.md                    # who Havan is + hard rules (never books)
   ├─ SOUL.md                        # voice: value over noise, ranked shortlist
   ├─ AGENTS.md                      # session/memory rules
   ├─ USER.md                        # the traveler profile (DUMMY — replace with yours)
   ├─ TOOLS.md / HEARTBEAT.md        # local notes / optional periodic price‑watch
   └─ skills/flight-finder/SKILL.md  # the search + rank procedure

Setup

1. Run an OpenClaw gateway with a chat channel (Telegram) and the browser tool enabled, and an LLM configured.
2. Point a new agent named havan at this agent-config/ directory (workspace), and bind your Telegram bot to it.
3. Edit agent-config/USER.md with your real home airports, currency, and preferences.
4. (Optional) copy .env.example → .env and add an Amadeus or Kiwi (Tequila) API key for structured results instead of screen‑scraping.
5. DM your bot: "Cheapest BER→LIS, last week of next month, carry‑on only, return."

Security notes

• No secrets in this repo. There are no credentials here; any optional flight‑API keys live in .env (gitignored). The traveler profile is fictional dummy data.
• Read‑only by design. Havan searches and recommends; it never enters payment details or books.
• Privacy. Trip details are personal — keep your real USER.md/memory in a private fork, and Havan won't surface them in group chats.

Credits

Part of a small family of OpenClaw‑orchestrated personal agents. Flight data via Google Flights / Skyscanner / OTAs (read through the browser); optional structured data via Amadeus or Kiwi. Runs on OpenClaw.