An agentic app that plans your morning trail run. Every time it fires, the agent:
- Checks your calendar for the morning's schedule
- Works out how much free time you have before your first meeting (with a get-ready buffer)
- Checks the weather —
Sunny,Shaded, orCloudy - Reads the approved-trails CSV (hike name, length, strenuous level, surrounding type)
- Suggests one trail that fits your time window and the weather, plus alternatives
The answer never appears alone — Trail-Scout prints its full working first. In agent mode you see every tool call and result live; in rule-based mode you get a step-by-step trace (calendar read, window math, weather, and the score for every trail) before the final pick. Add --quiet to skip the trace.
It runs in two modes:
| Mode | When | How it decides |
|---|---|---|
| Claude agent | ANTHROPIC_API_KEY is set |
A Claude tool-use loop (claude-opus-4-8 via the Anthropic SDK tool runner) calls the four tools and reasons about the best pick |
| Rule-based fallback | No API key, or --no-llm |
Deterministic scoring: filter trails by estimated duration vs. free minutes, then rank by weather↔surroundings fit |
All data sources are dummy/mock by design — swap them for real ones later (see Extending).
git clone https://github.com/abankar1/Trail-Scout.git
cd Trail-Scout
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
python main.pySample output (rule-based mode — the decision trace always comes before the answer):
Trail-Scout — morning run plan for 2026-07-17
====================================================
How this suggestion was made:
Step 1/4 Read calendar for 2026-07-17: 3 morning event(s) before 12:00.
- 08:30-09:00 1:1 with manager
...
Step 2/4 Compute free window: wake-up 06:30 -> 07:45 (first event '1:1 with
manager' at 08:30; includes a 45-min get-ready buffer) = 75 min for a run.
Step 3/4 Check weather: Sunny [mock (deterministic by date)].
Step 4/4 Evaluate 32 approved trails from data/trails.csv (assumed pace, min/km: ...):
+ Whispering Pines Loop: ~65 min fits; weather-fit 2/2 (shaded cover is
ideal in direct sun); window-use 0.87 -> score 2.87.
x Highland Traverse: 10.4 km Strenuous ~104 min — does NOT fit the 75-min window.
...
Decision Rank by score (weather fit + share of window used): ...
----------------------------------------------------
Weather: Sunny (mock (deterministic by date))
Free time: 75 min (06:30-07:45)
>> Whispering Pines Loop — 8.2 km, Moderate, Shaded forest (~65 min)
python main.py --date 2026-07-19 # plan another day
python main.py --no-llm # force the rule-based recommender
python main.py --quiet # suggestion only, skip the decision trace
WEATHER=Cloudy python main.py # override the mock weatherexport ANTHROPIC_API_KEY=sk-ant-...
python main.pyThe agent defines four tools (get_morning_schedule, get_available_time, get_weather, get_approved_trails) and lets Claude drive the loop until it lands on a suggestion. Every tool call and its result is printed live ([call] / [tool] lines) so you watch the agent gather its evidence before it answers, and the model is instructed to show its working — window, weather, ruled-in/ruled-out trails — ahead of the final pick. If the API call fails for any reason, the CLI falls back to the rule-based recommender automatically.
| File | Contents |
|---|---|
data/trails.csv |
32 approved trails: Hike Name, Length (km), Strenuous Level, Surrounding Type |
data/calendar.json |
Two weeks of fake calendar events starting from generation day |
Regenerate anytime:
python scripts/generate_data.py.github/workflows/daily-suggestion.yml runs the agent every morning (05:30 UTC) and on manual dispatch, writing the suggestion to the workflow run summary. It works with zero secrets in rule-based mode; add an ANTHROPIC_API_KEY repo secret to run the Claude agent instead.
main.py CLI entry point
trail_scout/
tools.py Data sources: calendar, time window, weather, CSV trails
agent.py Claude tool-use loop (Anthropic SDK tool runner)
recommend.py Rule-based fallback recommender
scripts/generate_data.py Dummy-data generator
data/ trails.csv + calendar.json (committed dummy data)
- Real calendar — replace
get_morning_schedule()intrail_scout/tools.pywith a Google Calendar / CalDAV fetch; the agent and fallback both consume the same shape. - Real weather — swap
get_weather()for a free API like Open-Meteo and map conditions ontoSunny/Shaded/Cloudy. - Your trails — edit
data/trails.csvdirectly; the header row is the only contract. - Pace tuning — adjust
PACE_MIN_PER_KMintools.pyto your own pace per difficulty level.
MIT