Trek Buddy: an offline trekking companion that runs its AI on your laptop, not in the cloud 🥾

Abhiyog Nejin — Mon, 12 Oct 2026 04:50:52 +0000

Entry for Hacktoberfest 2026, Week 1: "Touch Grass" — build something with open-source AI that gets people off the screen and into the world.

Picture this: you're standing at the top of Chembra Peak, looking down at the heart-shaped lake, your phone showing zero signal bars. Your friend pulls up three different trekking apps and every single one is useless — no cached data, no offline briefings, and the one "AI trail assistant" needs the cloud just to tell you what to pack. That exact frustration is why I built Trek Buddy.

The premise is simple: if the whole point of an app is to help you on a trail, it has to work where trails actually are — offline. And once you commit to offline-first, the AI has to follow: no cloud calls, no API keys, no subscription. Just an open-weight model running on your own machine.

What I Built

10 curated Kerala trails — Chembra, Meesapulimala, Agasthyarkoodam, Kolukkumalai, Paithalmala, Ranipuram, Pakshipathalam, Brahmagiri, Dhoni Hills, Ilaveezhapoonchira. Filter by difficulty, and each one carries distance, duration, best months, highlights, and whether you need forest department permission.
Weather check with a backbone — pulls forecasts from Open-Meteo (free, no API key), and it understands Kerala's monsoon: heavy rain, violent showers, and thunderstorms get flagged as rethink your plans, not just shown as an icon.
A packing checklist that actually thinks — generated from the trail's difficulty, the season, and live weather. Pick a trail in July and it'll tell you to bring leech socks. Pick a moderate trail in pouring rain and rain gear jumps to the top. This is the kind of detail that makes or breaks a trek.
An AI trail briefing from a model on your laptop — via Ollama and any open-weight model (I use gemma3). It writes a personalized briefing for your chosen trail: what to expect, how to pace, what to watch out for. No Ollama installed? It falls back to built-in guide notes, and everything else works identically.
Fully offline mode — forecasts are cached as JSON, so with zero signal the app keeps working off your last check. Your diary of completed treks lives in a local file too. Nothing ever leaves your machine.

Demo

Here's a real session — browsing trails, picking Chembra Peak, and getting the weather-aware plan in one go:

--- Trek Buddy 🥾 ---  (type 'quit' to exit)

1. Browse trails
2. Filter by difficulty
3. View trek diary

What do you want to do? (1/2/3 or quit): 1

  1. Chembra Peak (Wayanad) — moderate, 9 km
  2. Meesapulimala (Idukki) — hard, 8 km
  3. Agasthyarkoodam (Thiruvananthapuram) — hard, 28 km
  ... (10 Kerala trails total)

Pick a trail (number): 1

🥾  Chembra Peak — Wayanad
  Difficulty   : moderate
  Distance     : 9 km
  Duration     : 4-5 hours round trip
  Best months  : Sep–May
  Permission   : Forest dept permission from Meppady office; limited daily slots

Checking weather...
🌦️  Light drizzle, 16.4°C — wind 6.9 km/h (live)
🌧️  Rain expected — pack rain gear and watch for slippery trails.

🎒  Packing checklist:
    [ ] 2L water (minimum)
    [ ] Snacks / energy bars
    [ ] First-aid kit
    [ ] Fully charged phone + power bank
    [ ] Trekking shoes with grip
    [ ] Trekking pole
    [ ] Raincoat / poncho
    [ ] Dry bag for phone

📖  Guide notes:
Difficulty is moderate — 4-5 hours round trip. Don't miss: heart-shaped
Hridaya Saras lake. Permission required: Forest dept permission from Meppady
office; limited daily slots. Leech territory — tuck your pants into your socks.

With Ollama running, the guide notes are replaced by a personalized AI briefing written by gemma3 on your own machine. Without internet, the same screen renders from the cached forecast instead — the app never breaks.

Code

The whole thing is one Python file — 100% standard library, no dependencies to install:

trek_buddy.py (370 lines — click to expand)

"""
Trek Buddy — your offline trekking companion for Kerala. 🥾

Pick a trail, check the weather, get a packing checklist, and get a trail
briefing from a local AI running 100% on your own machine (no internet,
no API keys, no data leaving your laptop).

How to run:
    python trek_buddy.py

Optional AI layer:
    1. Install Ollama from https://ollama.com
    2. Pull a small open-weight model:  ollama pull gemma3
    3. Make sure Ollama is running (it starts automatically)

Without Ollama the app still works fully — the briefing just comes from
the built-in guide notes instead of the local model.

Trail coordinates are approximate (district level) — good enough for a
weather check, not for navigation. Always trek with a guide where required.
"""

import datetime
import json
import os
import urllib.parse
import urllib.request

BASE_DIR = os.path.dirname(os.path.abspath(__file__))
TRAILS_FILE = os.path.join(BASE_DIR, "trails.json")
CACHE_FILE = os.path.join(BASE_DIR, "weather_cache.json")
LOG_FILE = os.path.join(BASE_DIR, "trip_log.json")

WEATHER_URL = "https://api.open-meteo.com/v1/forecast"
OLLAMA_URL = "http://localhost:11434/api/generate"
OLLAMA_TAGS_URL = "http://localhost:11434/api/tags"

# WMO weather codes -&gt; description + emoji (same mapping as the weather app)
WEATHER_CODES = {
    0: ("Clear sky", "☀️"), 1: ("Mainly clear", "🌤️"),
    2: ("Partly cloudy", "⛅"), 3: ("Overcast", "☁️"),
    45: ("Fog", "🌫️"), 48: ("Icy fog", "🌫️"),
    51: ("Light drizzle", "🌦️"), 53: ("Drizzle", "🌦️"),
    55: ("Heavy drizzle", "🌦️"), 61: ("Light rain", "🌧️"),
    63: ("Rain", "🌧️"), 65: ("Heavy rain", "⛈️"),
    71: ("Light snow", "🌨️"), 73: ("Snow", "🌨️"),
    75: ("Heavy snow", "❄️"), 80: ("Light showers", "🌦️"),
    81: ("Showers", "🌧️"), 82: ("Violent showers", "⛈️"),
    95: ("Thunderstorm", "⛈️"), 96: ("Thunderstorm with hail", "⛈️"),
    99: ("Thunderstorm with hail", "⛈️"),
}

# Weather codes that should make you think twice about trekking
BAD_WEATHER = {65, 82, 95, 96, 99}
RAINY_WEATHER = {51, 53, 55, 61, 63, 80, 81}

BASE_PACKING = [
    "2L water (minimum)",
    "Snacks / energy bars",
    "First-aid kit",
    "Fully charged phone + power bank",
    "Sunscreen and cap",
]

MONSOON_MONTHS = {"Jun", "Jul", "Aug", "Sep"}


# ---------- data loading ----------

def load_trails():
    """Read the curated trail database."""
    with open(TRAILS_FILE) as f:
        return json.load(f)["trails"]


def load_cache():
    """Read cached weather forecasts (used when offline)."""
    if not os.path.exists(CACHE_FILE):
        return {}
    try:
        with open(CACHE_FILE) as f:
            return json.load(f)
    except (json.JSONDecodeError, OSError):
        return {}


def save_cache(cache):
    """Persist weather forecasts for offline use."""
    with open(CACHE_FILE, "w") as f:
        json.dump(cache, f, indent=2)


def load_log():
    """Read the trip diary."""
    if not os.path.exists(LOG_FILE):
        return []
    try:
        with open(LOG_FILE) as f:
            return json.load(f)
    except (json.JSONDecodeError, OSError):
        return []


def save_log(entries):
    """Persist the trip diary."""
    with open(LOG_FILE, "w") as f:
        json.dump(entries, f, indent=2)


# ---------- weather (Open-Meteo, cached for offline use) ----------

def fetch_weather(lat, lon):
    """Fetch the current weather from Open-Meteo (free, no key)."""
    params = urllib.parse.urlencode({
        "latitude": lat,
        "longitude": lon,
        "current": "temperature_2m,weather_code,wind_speed_10m",
        "timezone": "auto",
    })
    with urllib.request.urlopen(f"{WEATHER_URL}?{params}", timeout=10) as r:
        return json.loads(r.read().decode())["current"]


def get_weather(trail):
    """Get weather for a trail — live if online, cached if offline.

    Returns (weather_dict, was_cached).
    """
    cache = load_cache()
    try:
        weather = fetch_weather(trail["lat"], trail["lon"])
        weather["fetched_at"] = datetime.datetime.now().strftime("%Y-%m-%d %H:%M")
        cache[trail["id"]] = weather
        save_cache(cache)
        return weather, False
    except Exception:
        # Offline — fall back to the last cached forecast
        if trail["id"] in cache:
            return cache[trail["id"]], True
        return None, True


def weather_warning(code):
    """Return a warning string for bad trekking weather, or None."""
    if code in BAD_WEATHER:
        return "⚠️  Heavy rain or thunderstorm — seriously consider postponing this trek."
    if code in RAINY_WEATHER:
        return "🌧️  Rain expected — pack rain gear and watch for slippery trails."
    return None


# ---------- local AI layer (Ollama, 100% on-device) ----------

def ollama_model():
    """Return the name of a usable local model, or None if Ollama is down."""
    try:
        with urllib.request.urlopen(OLLAMA_TAGS_URL, timeout=3) as r:
            models = json.loads(r.read().decode()).get("models", [])
        if models:
            return models[0]["name"]
        return None
    except Exception:
        return None


def ask_local_model(prompt, model):
    """Send a prompt to the local model and return its reply (no streaming)."""
    body = json.dumps({
        "model": model,
        "prompt": prompt,
        "stream": False,
    }).encode()
    req = urllib.request.Request(
        OLLAMA_URL, data=body, headers={"Content-Type": "application/json"}
    )
    with urllib.request.urlopen(req, timeout=120) as r:
        return json.loads(r.read().decode())["response"].strip()


def ai_briefing(trail, weather, model):
    """Ask the local model for a trail briefing. Returns None on failure."""
    text, _ = WEATHER_CODES.get(weather["weather_code"], ("Unknown", "🌡️"))
    prompt = (
        f"You are a friendly Kerala trekking guide. Trail: {trail['name']} "
        f"({trail['district']}, {trail['difficulty']}, {trail['distance_km']} km, "
        f"{trail['duration']}). Current weather there: {text}, "
        f"{weather['temperature_2m']}°C. Highlights: "
        f"{', '.join(trail['highlights'])}. "
        "Give a short trail briefing: what to expect, one safety tip, "
        "and one thing to look forward to. Under 120 words. "
        "Warm tone, no fluff."
    )
    try:
        return ask_local_model(prompt, model)
    except Exception:
        return None


def guide_notes(trail):
    """Rule-based briefing used when no local model is available."""
    notes = [
        f"Difficulty is {trail['difficulty']} — {trail['duration']}.",
        f"Don't miss: {trail['highlights'][0].lower()}.",
    ]
    if trail["permission_needed"]:
        note = trail["permission_note"].rstrip(".")
        notes.append(f"Permission required: {note}.")
    if trail["leech_risk"]:
        notes.append("Leech territory — tuck your pants into your socks.")
    return " ".join(notes)


# ---------- packing checklist ----------

def packing_checklist(trail, weather):
    """Build a packing list from trail difficulty, season, and live weather."""
    items = list(BASE_PACKING)
    month = datetime.datetime.now().strftime("%b")

    if trail["difficulty"] in ("moderate", "hard"):
        items += ["Trekking shoes with grip", "Trekking pole"]
    if trail["difficulty"] == "hard":
        items += ["Headlamp", "Extra food for the long haul"]
    if trail["leech_risk"] and month in MONSOON_MONTHS:
        items += ["Leech socks", "Salt / sanitizer for leeches"]
    if weather and weather["weather_code"] in RAINY_WEATHER | BAD_WEATHER:
        items += ["Raincoat / poncho", "Dry bag for phone"]
    if weather and weather["temperature_2m"] &lt; 15:
        items += ["Warm layer / jacket"]
    return items


# ---------- UI ----------

def show_trail(trail, index):
    print(f"  {index}. {trail['name']} ({trail['district']}) — "
          f"{trail['difficulty']}, {trail['distance_km']} km")


def show_trail_detail(trail):
    print(f"\n🥾  {trail['name']} — {trail['district']}")
    print("-" * 45)
    print(f"  Difficulty   : {trail['difficulty']}")
    print(f"  Distance     : {trail['distance_km']} km")
    print(f"  Duration     : {trail['duration']}")
    print(f"  Best months  : {', '.join(trail['best_months'])}")
    if trail["permission_needed"]:
        print(f"  Permission   : {trail['permission_note']}")
    print("  Highlights   :")
    for h in trail["highlights"]:
        print(f"    • {h}")
    print()


def show_weather(weather, cached):
    text, emoji = WEATHER_CODES.get(weather["weather_code"], ("Unknown", "🌡️"))
    tag = f"(cached, {weather.get('fetched_at', 'unknown time')})" if cached else "(live)"
    print(f"{emoji}  {text}, {weather['temperature_2m']}°C "
          f"— wind {weather['wind_speed_10m']} km/h {tag}")
    warning = weather_warning(weather["weather_code"])
    if warning:
        print(warning)
    print()


def plan_trek(trail):
    """Walk through weather, checklist, and briefing for one trail."""
    show_trail_detail(trail)

    print("Checking weather...")
    weather, cached = get_weather(trail)
    if weather is None:
        print("No weather data and nothing cached — you're fully offline. "
              "The rest still works.\n")
    else:
        if cached:
            print("📴 Offline mode — showing the last cached forecast.\n")
        show_weather(weather, cached)

    print("🎒  Packing checklist:")
    for item in packing_checklist(trail, weather):
        print(f"    [ ] {item}")
    print()

    model = ollama_model()
    if model:
        print(f"🤖  Asking your local AI ({model}) for a trail briefing...")
        briefing = ai_briefing(trail, weather or {"weather_code": 0,
                                                 "temperature_2m": "?"},
                              model)
        if briefing:
            print(f"\n{briefing}\n")
        else:
            print("The local model didn't answer — here's the guide notes instead:\n")
            print(guide_notes(trail) + "\n")
    else:
        print("💡 Tip: install Ollama (https://ollama.com) and run "
              "'ollama pull gemma3' for AI briefings.\n")
        print("📖  Guide notes:")
        print(guide_notes(trail) + "\n")

    choice = input("Log this trek in your diary? (y/n): ").strip().lower()
    if choice == "y":
        entries = load_log()
        entries.append({
            "trail": trail["name"],
            "date": datetime.datetime.now().strftime("%Y-%m-%d"),
            "difficulty": trail["difficulty"],
        })
        save_log(entries)
        print("Logged! 📓\n")
    else:
        print()


def show_diary():
    entries = load_log()
    if not entries:
        print("\nYour diary is empty — go touch some grass first. 🌱\n")
        return
    print("\n📓  Your trek diary:")
    for e in entries:
        print(f"  • {e['date']} — {e['trail']} ({e['difficulty']})")
    print()


def main():
    trails = load_trails()
    print("\n--- Trek Buddy 🥾 ---  (type 'quit' to exit)\n")

    while True:
        print("1. Browse trails")
        print("2. Filter by difficulty")
        print("3. View trek diary")
        choice = input("\nWhat do you want to do? (1/2/3 or quit): ").strip().lower()
        if choice in ("quit", "q", "exit"):
            print("See you on the trail! 🏔️")
            break

        if choice == "2":
            level = input("Difficulty (easy/moderate/hard): ").strip().lower()
            options = [t for t in trails if t["difficulty"] == level]
            if not options:
                print("No trails at that difficulty.\n")
                continue
        elif choice == "1":
            options = trails
        else:
            print("Pick 1, 2, 3 or quit.\n")
            continue

        print()
        for i, t in enumerate(options, start=1):
            show_trail(t, i)
        try:
            pick = int(input("\nPick a trail (number): ").strip())
            if 1 &lt;= pick &lt;= len(options):
                plan_trek(options[pick - 1])
            else:
                print("Invalid number.\n")
        except ValueError:
            print("That's not a number.\n")


if __name__ == "__main__":
    main()

Repo: [REPO LINK — dropping this in as soon as my GitHub account is back]

How I Built It

Zero cost to run — a student-friendly budget (mine is effectively zero) can ship a real AI feature, because inference happens locally.
Privacy by construction — your trail plans, your location, your diary never touch a server. For an app that knows where you hike, that matters.
Graceful degradation — the app is designed live → cached → offline, and the AI layer follows the same philosophy: local model → built-in notes → still a great app.

Trek Buddy is 100% Python standard library — no dependencies to install, nothing to break on a friend's old laptop. python trek_buddy.py and you're in.

The honest limitations

Trail coordinates are district-level (good enough for a weather check, not for navigation), and permissions and seasons change, so it reminds you to check with the forest department before heading out — especially for Agasthyarkoodam and Meesapulimala. And it won't replace a local guide on trails where one is required. Tech should make trekking safer, not dumber.

Prize Categories

Best Use of Gemma — Trek Buddy's AI briefings run on gemma3 through Ollama, entirely on the user's own machine. No cloud, no API key, no data leaving the laptop — which is exactly the point for an app meant for places with zero signal.

What's next

I'd love to add trail maps that render in the terminal, Malayalam-language briefings, GPX import for custom routes, and trails beyond Kerala. But for now: ten trails, honest weather, smart packing, and an AI that works where the internet doesn't.

Cover photo: Chembra Peak by Aneesh Jose (CC BY-SA 3.0).

DEV Community: Abhiyog Nejin