TrailBuddy: a local-first AI hiking companion that gets you off the screen

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

TrailBuddy is a hiking companion that runs entirely on your own machine. You pick a real trail from your own GPX files, and a local open-weight model gives you a handful of small observation missions and a safety checklist for that trail, such as "listen for three different bird calls" or "find something that is growing on a tree it didn't start on."

While you walk, you tell it what you spotted and it ticks the missions off for you. You can photograph something and get a short description of it. A Touch Grass Score goes up with missions completed, discoveries and time outside, and goes down with screen time. When you finish, the model writes a short first-person journal of the outing and saves it as Markdown and as a shareable HTML report.

The idea is simple: the screen should be the shortest part of the walk. TrailBuddy gives you a reason to look up (a mission), asks you to put the phone away, and only needs a few seconds of screen time to log what you found. It is for anyone who wants a reason to go on a walk or a hike, especially people who want an AI helper without sending their location, photos or journal to a server they don't control.

One design rule I stuck to: the model never invents routes. It only works with real trails you supply as GPX files. The model writes the missions and the journal. The distance, climb and time estimates come from the GPX data.

Demo

TrailBuddy is built to run locally, so there is no hosted link. Setup takes a few minutes and is in the README.

Code

aryanguptacsvtu / Trail-Buddy

TrailBuddy

TrailBuddy is an offline, voice-first hiking companion. It chooses from real GPX trails, suggests short observation missions, answers questions with a local Ollama model, and saves a short journal after the outing.

You can use it two ways:

• Web UI (serve.py): a local browser interface with a trail picker, mission tracker, timers, photo scanner, chat and journal.
• Command line (run.py): the original voice-first, keyboard-driven mode.

Everything runs on your machine. The browser talks to a small local server, and that server talks to Ollama.

What you need

• Python 3.10 or newer
• Ollama with a local model
• A microphone and speakers for voice mode (command line only)
• Optional: a Piper voice model for spoken replies (command line only)
• Optional: a vision-capable model such as gemma3:4b for the web UI photo scanner

TrailBuddy does not create or navigate routes. Add GPX files exported from an online route…

View on GitHub

MIT licensed. Python 3.10+, standard-library web server, no frontend framework.

How I Built It

Open-source pieces:

• Gemma 3 (4B) through Ollama. This is the model behind everything: it writes missions and safety checklists, answers questions during the walk, works out which mission you've just completed from what you say, describes photos (Gemma 3 is multimodal) and writes the journal. The model name is set by one environment variable, TB_MODEL, so you can swap it for another model such as qwen3:4b.
• faster-whisper for local speech-to-text and Piper for local text-to-speech in the command-line, voice-first mode.

How it fits together:

Browser (HTML + CSS + vanilla JS)
   │  JSON over localhost
   |
Python standard-library server (web.py)
   │            │
router.py     llm.py --> Ollama --> Gemma
(GPX → km, climb, minutes)

• router.py reads the GPX files and works out distance, elevation gain and estimated time. This is plain code, so the trail facts are never made up by the model.
• llm.py is the only part that talks to the model. It has separate prompts for planning, mission detection, replies and the journal, with a shared safety instruction so the model doesn't give risky advice.
• web.py is a small http.server app that serves the page and a few JSON endpoints. I deliberately used no web framework and no front-end build step, so the whole project installs with a short requirements.txt.
• The same core also powers a command-line mode (run.py) for hands-free use with voice.

Lessons from building it:

1. Don't leave hard constraints to the model. My first version asked for "what kind of outing" and a time budget, then let the model choose one trail. With a 6-minute budget, no trail fit, so the router quietly fell back to showing all of them, and the model, which was never told the budget, picked a 35-minute loop that matched "moderate fitness." I removed the form. Now every trail is shown as a card, so you choose, and the model only does what it is good at: writing the missions and checklist for the trail you picked. Listing trails needs no model call at all, so it's instant.

2. Let code do the facts. Distances, climb and times come from the GPX, and the model gets them as input. Small local models are fine at writing and poor at arithmetic.

3. Be honest about the limits. The photo scanner can be wrong, so the prompt asks for at most two short sentences and an interesting fact only when it is confident. The README also warns people never to use it to identify mushrooms or foraged food.

Current limitations: you need a device that can run Ollama (a laptop for now), trails must come from GPX files you supply, the screen-time meter is manual, and the web UI has no voice input (the command-line mode does). Next steps are a phone-friendly or Raspberry Pi setup and filtering trails by time and fitness.

Why Does Open Innovation Matter?

A hiking app is the kind of tool that should work where the signal doesn't. Open-weight models made three things possible that a closed API wouldn't have:

• It works offline. Once the model, the speech model and your GPX files are downloaded, TrailBuddy needs no internet. A cloud API would turn every question on a remote trail into a failed request.
• Your data stays with you. TrailBuddy never sends your location, your photos of whatever you found, or your journal to any server. Everything is processed by a model running on your own machine. For an app that knows where you walk and when, that matters.
• You can swap and inspect the model. One environment variable changes the model. You can choose a bigger one for better writing or a smaller one for older hardware, and there are no API keys, per-call costs or rate limits to plan around.

It also means anyone can read, change and extend the whole stack: the code is MIT licensed and sits on open models and tools.

Prize Categories

• Best Use of Gemma: Gemma 3 (4B), run locally through Ollama, powers every AI feature: mission writing, mission detection from natural language, photo understanding and the journal.