How sarathchowdary05-commits/trailbuddy works
TrailBuddy is a conversational trail-running advisor with CLI and web chat entry points. A user message reaches a stateful Claude-backed agent, which dispatches tools for trail-list lookup, live conditions, or a weather-aware recommendation; recommendations apply AQI skip rules and rank trails by time and shade fit. Both interfaces load configuration and the personal TOML trail list, while weather comes from Open-Meteo. The sampled source shows these runtime paths; the README describes capabilities consistently, though the static UI implementation was not sampled.
Main entry points: web.py Web chat API · cli.py CLI chat · agent.py Agent tools · trails.py Trail loader
Components 14
Chat interfaces
- CLI chat
src/trailbuddy/cli.py - Web chat API
src/trailbuddy/web.py - Browser UI
src/trailbuddy/static/index.html
Conversation and tools
- Chat agent
src/trailbuddy/agent.py - Agent tools
src/trailbuddy/agent.py
Trail and conditions
- Trail loader
src/trailbuddy/trails.py - Personal trail list
trails.toml - Weather client
src/trailbuddy/weather.py - Trail scoring
src/trailbuddy/recommend.py - Domain data
src/trailbuddy/models.py
Configuration
- Runtime settings
src/trailbuddy/config.py
Other components
- Runner
- Anthropic Claude
- Open-Meteo
Connections 18
- Runner → CLI chat: starts CLI
- Runner → Web chat API: opens web chat
- Browser UI → Web chat API: sends messages
- CLI chat → Runtime settings: loads settings
- Web chat API → Runtime settings: loads settings
- CLI chat → Trail loader: loads trails
- Web chat API → Trail loader: loads trails
- Trail loader → Personal trail list: reads TOML
- CLI chat → Chat agent: sends chat
- Web chat API → Chat agent: creates session agent
- Chat agent → Anthropic Claude: runs tool chat
- Anthropic Claude → Agent tools: dispatches calls
- Agent tools → Weather client: fetches conditions
- Agent tools → Trail scoring: scores options
- Agent tools → Domain data: uses trail and condition data
- Trail scoring → Domain data: returns recommendation data
- Weather client → Open-Meteo: requests forecast and air quality
- Open-Meteo → Weather client: returns readings